ezship 0.1.14 → 0.1.15

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/commands.d.mts CHANGED
@@ -378,12 +378,12 @@ export const LISTENER_MAX: number;
378
378
  export const LISTENER_BASE_PATH: "/_ez/listeners/";
379
379
  export const WEBHOOK_SCHEMES: readonly ["standard", "stripe", "github", "token"];
380
380
  export const LISTENER_OVERLAP_HOURS: { readonly default: number; readonly max: number };
381
- /** The Site API (docs/adr/0119): `<prefix>/_ez/api/...` with `Authorization: Bearer ezk_...`. */
381
+ /** The Data API (docs/adr/0151): `/_ez/api/...` on the app origin with `Authorization: Bearer ezk_...`. */
382
382
  export const API_BASE_PATH: "/_ez/api";
383
383
  export const API_KEY_PREFIX: "ezk_";
384
384
  export const API_KEY_NAME_RE: RegExp;
385
385
  export const API_KEY_DAYS: { readonly default: number; readonly max: number };
386
- export const API_KEYS_PER_SITE: number;
386
+ export const API_KEYS_PER_INSTANCE: number;
387
387
  export const API_KEY_RATE: { readonly burst: number; readonly perSecond: number };
388
388
  export const LISTENER_BODY_MAX: number;
389
389
  /** The entries of a listeners.json, every problem with it, and the listeners/ files it does not name. */
package/commands.mjs CHANGED
@@ -227,21 +227,21 @@ export const LISTENER_OVERLAP_HOURS = Object.freeze({ default: 24, max: 168 });
227
227
  /** @type {typeof import("./commands.d.mts").LISTENER_BODY_MAX} */
228
228
  export const LISTENER_BODY_MAX = 256_000;
229
229
  /**
230
- * The Site API (docs/adr/0119): other systems reach a Site's data under `<prefix>/_ez/api/` with an API Key,
231
- * `Authorization: Bearer ezk_...`, before the Member gate.
230
+ * The Data API (docs/adr/0119, docs/adr/0151): other systems reach an Instance's data under `/_ez/api/` on its
231
+ * app origin with an API Key, `Authorization: Bearer ezk_...`.
232
232
  * @type {typeof import("./commands.d.mts").API_BASE_PATH}
233
233
  */
234
234
  export const API_BASE_PATH = "/_ez/api";
235
235
  /** @type {typeof import("./commands.d.mts").API_KEY_PREFIX} */
236
236
  export const API_KEY_PREFIX = "ezk_";
237
- /** An API Key's name: permanent on its Site, the `<name>` of its actor `key:<site>/<name>`. */
237
+ /** An API Key's name: permanent on its Instance, the `<name>` of its actor `key:<name>`. */
238
238
  /** @type {typeof import("./commands.d.mts").API_KEY_NAME_RE} */
239
239
  export const API_KEY_NAME_RE = /^[a-z][a-z0-9-]{0,39}$/;
240
240
  /** How long a new API Key lasts, in days. */
241
241
  /** @type {typeof import("./commands.d.mts").API_KEY_DAYS} */
242
242
  export const API_KEY_DAYS = Object.freeze({ default: 90, max: 365 });
243
- /** @type {typeof import("./commands.d.mts").API_KEYS_PER_SITE} */
244
- export const API_KEYS_PER_SITE = 20;
243
+ /** @type {typeof import("./commands.d.mts").API_KEYS_PER_INSTANCE} */
244
+ export const API_KEYS_PER_INSTANCE = 50;
245
245
  /** Each key's token bucket on the door: `burst` requests, refilled at `perSecond`. */
246
246
  /** @type {typeof import("./commands.d.mts").API_KEY_RATE} */
247
247
  export const API_KEY_RATE = Object.freeze({ burst: 120, perSecond: 20 });
@@ -3920,12 +3920,12 @@ export const ROUTES = Object.freeze({
3920
3920
  path: `${SITE}/listeners/:name/events/:id/retry`,
3921
3921
  args: (name, id) => ({ params: { name, id } }),
3922
3922
  },
3923
- // API Keys (docs/adr/0119): Admins create and revoke them; every Builder of the Site lists them.
3924
- listApiKeys: { method: "GET", path: `${SITE}/keys` },
3925
- createApiKey: { method: "POST", path: `${SITE}/keys`, args: (input) => body(input) },
3923
+ // API Keys (docs/adr/0119, docs/adr/0151): the Instance's; Admins create and revoke, every Builder lists.
3924
+ listApiKeys: { method: "GET", path: `${INSTANCE}/keys` },
3925
+ createApiKey: { method: "POST", path: `${INSTANCE}/keys`, args: (input) => body(input) },
3926
3926
  revokeApiKey: {
3927
3927
  method: "DELETE",
3928
- path: `${SITE}/keys/:name`,
3928
+ path: `${INSTANCE}/keys/:name`,
3929
3929
  args: (name) => ({ params: { name } }),
3930
3930
  },
3931
3931
  callFunction: {
@@ -4779,31 +4779,35 @@ conversation); until then every delivery is refused.
4779
4779
  effect on the payload's own id with a unique index, and pass event.deliveryId to services as the idempotency
4780
4780
  key. \`ez listener events <name> [--dead]\`, \`show\` and \`retry\` inspect and replay events.`;
4781
4781
 
4782
- /** `ez help api`: the Site API and its API Keys (docs/adr/0119). */
4783
- const API_TOPIC = `The Site API lets another system (a sync job, a reporting tool, a script on the customer's server) read
4784
- and write this Site's data over HTTPS. Pages never use it: they have useLive and db.
4785
- An Admin creates an API Key in a terminal: \`ez key create warehouse --groups warehouse [--expires <days>]\`
4786
- prints the key (${API_KEY_PREFIX}...) once; give it to the other system as a secret, never through this conversation
4787
- or in Site code. \`ez key list\` shows every key (never the key itself), \`ez key revoke <name>\` ends one.
4788
- [runtime] A key acts as its own principal, key:<site>/<name>, decided as an active Member who holds only the
4782
+ /** `ez help api`: the Data API and its API Keys (docs/adr/0119, docs/adr/0151). */
4783
+ const API_TOPIC = `The Data API lets another system (a sync job, a reporting tool, a script on the customer's server) read
4784
+ and write this Instance's data over HTTPS. Pages never use it: they have useLive and db.
4785
+ An Admin creates an API Key in a terminal, from any Working Copy of the Instance: \`ez key create warehouse
4786
+ --groups warehouse [--sites <all | ids>] [--expires <days>]\` prints the key (${API_KEY_PREFIX}...) once; give it to the
4787
+ other system as a secret, never through this conversation or in Site code. \`ez key list\` shows every key
4788
+ (never the key itself), \`ez key revoke <name>\` ends one. A key's groups and Sites are fixed when it is created.
4789
+ [runtime] A key acts as its own principal, key:<name>, decided as an active Member who holds only the
4789
4790
  key's groups (and those they imply) and no MEMBER identity: global/db/access.sql applies with its row
4790
4791
  conditions, owner is the rows the key wrote, "= me" never matches, BY functions and BY none refuse its
4791
4792
  writes, and rules, workflows, defaults and History run as for a page. Give access by group:
4792
4793
  GROUP warehouse;
4793
4794
  READ orders WHERE group(warehouse) OR owner;
4794
- Requests go to <app url>/_ez/api/... with "Authorization: Bearer <key>" and JSON bodies; a browser's
4795
+ Requests go to <app origin>/_ez/api/... with "Authorization: Bearer <key>" and JSON bodies; a browser's
4795
4796
  request (one with an Origin header) is refused. GET _ez/api says who the key is; GET _ez/api/openapi.json
4796
- describes what it may reach. _ez/api/db/<table> is the page's data API: POST <table>/query, POST
4797
+ describes what it may reach. It serves the published schema as far as the App Database holds it: a Table or
4798
+ column is there once a Preview or Deploy has created it. _ez/api/db/<table> is the page's data API: POST <table>/query, POST
4797
4799
  <table>/aggregate, GET <table>/<id>, POST <table> (insert), PATCH and DELETE <table>/<id>, POST
4798
4800
  <table>/<id>/actions/<action>; ?why= gives a write its reason. The change feed is the History:
4799
4801
  POST _ez/api/db/<table>_history/query {"where":{"version":{"gt":<last seen>}},"order":["version"]}.
4800
4802
  Server functions are callable by a key only when they say so: serverFunction(input, handler, { api: true })
4801
- [check: function-options]; POST _ez/api/functions/<name> {"input": ...} answers {"result": ...}, against the
4802
- deployed Site, under the function's own access and authority. In the handler a key's user is
4803
- { id: "key:<site>/<name>", email: "", name, me: null, groups }. Files: POST
4803
+ [check: function-options], and only on the Sites its --sites allows. [runtime] Without --sites a key calls no
4804
+ functions, all means every unrestricted Site, and a Restricted Site is reached only by a key that names its id;
4805
+ --sites never narrows data, which groups do. POST _ez/api/sites/<site>/functions/<name> {"input": ...} answers
4806
+ {"result": ...}, against that Site's deployed artifact, under the function's own access and authority. In the
4807
+ handler a key's user is { id: "key:<name>", email: "", name, me: null, groups }. Files: POST
4804
4808
  _ez/api/attachments/<table>/<column>?name=<file> with the bytes, GET _ez/api/attachments/<id>.
4805
4809
  [runtime] Each key may make ${API_KEY_RATE.burst} requests at once, refilled at ${API_KEY_RATE.perSecond} a second (429 with Retry-After
4806
- past that). A key lasts ${API_KEY_DAYS.default} days by default, at most ${API_KEY_DAYS.max}; a Site holds at most ${API_KEYS_PER_SITE} active keys. A
4810
+ past that). A key lasts ${API_KEY_DAYS.default} days by default, at most ${API_KEY_DAYS.max}; an Instance holds at most ${API_KEYS_PER_INSTANCE} active keys. A
4807
4811
  name is never reused: to rotate, create a new key, switch the other system to it, revoke the old one.
4808
4812
  Previews have no API.`;
4809
4813
 
@@ -5383,7 +5387,7 @@ export const HELP_TOPICS = Object.freeze([
5383
5387
  },
5384
5388
  {
5385
5389
  name: "api",
5386
- summary: "the Site API: API Keys that let other systems read and write this Site's data",
5390
+ summary: "the Data API: API Keys that let other systems read and write this Instance's data",
5387
5391
  text: () => API_TOPIC,
5388
5392
  },
5389
5393
  {
@@ -5732,11 +5736,11 @@ export const COMMANDS = [
5732
5736
  },
5733
5737
  {
5734
5738
  usage: "ez key list",
5735
- help: "this site's API Keys: name, groups, state, expiry and last use, never the key (ez help api)",
5739
+ help: "this instance's API Keys: name, groups, sites, state, expiry and last use, never the key (ez help api)",
5736
5740
  },
5737
5741
  {
5738
- usage: "ez key create <name> [--groups <a,b>] [--expires <days>]",
5739
- help: "admins: an API Key another system uses to reach this site's data; printed once",
5742
+ usage: "ez key create <name> [--groups <a,b>] [--sites <all | ids>] [--expires <days>]",
5743
+ help: "admins: an API Key another system uses to reach this instance's data; printed once",
5740
5744
  },
5741
5745
  {
5742
5746
  usage: "ez key revoke <name>",
@@ -6372,7 +6376,7 @@ function integrationLines(i) {
6372
6376
  * @param {string} cmd @param {string[]} pos
6373
6377
  */
6374
6378
  const GLOBAL_REFUSES = (cmd, pos) =>
6375
- ["deploy", "preview", "link", "config", "function", "listener", "key"].includes(cmd) ||
6379
+ ["deploy", "preview", "link", "config", "function", "listener"].includes(cmd) ||
6376
6380
  (cmd === "site" && pos[0] === "access");
6377
6381
 
6378
6382
  /** @param {Workspace} ws @param {string[]} argv @param {string} [stdin] @returns {Promise<{text: string, data: unknown}>} */
@@ -7823,10 +7827,10 @@ async function execute(ws, argv, stdin) {
7823
7827
  }
7824
7828
 
7825
7829
  case "key": {
7826
- // docs/adr/0119: an API Key is shown once, by create, and never again.
7830
+ // docs/adr/0119, docs/adr/0151: the Instance's API Keys, each shown once, by create, and never again.
7827
7831
  const syntax =
7828
- "ez key list | create <name> [--groups <a,b>] [--expires <days>] | revoke <name>";
7829
- const VALUES = ["--groups", "--expires"];
7832
+ "ez key list | create <name> [--groups <a,b>] [--sites <all | ids>] [--expires <days>] | revoke <name>";
7833
+ const VALUES = ["--groups", "--sites", "--expires"];
7830
7834
  /** @type {Record<string, string>} */
7831
7835
  const given = {};
7832
7836
  const words = [];
@@ -7850,6 +7854,7 @@ async function execute(ws, argv, stdin) {
7850
7854
  k.state,
7851
7855
  `${k.prefix}...`,
7852
7856
  `groups: ${k.groups.length ? k.groups.join(", ") : "none"}`,
7857
+ `sites: ${k.sites === "all" ? "all" : k.sites.length ? k.sites.join(", ") : "none"}`,
7853
7858
  k.state === "revoked" && k.revokedAt
7854
7859
  ? `revoked ${utcMinute(k.revokedAt)}`
7855
7860
  : `expires ${utcMinute(k.expiresAt)}`,
@@ -7870,6 +7875,14 @@ async function execute(ws, argv, stdin) {
7870
7875
  if (sub === "create") {
7871
7876
  const groups = given["--groups"]?.split(",").map((g) => g.trim()) ?? [];
7872
7877
  if (groups.some((g) => !g)) throw new Error("--groups is a comma-separated list of names.");
7878
+ /** @type {"all" | string[] | undefined} */
7879
+ let sites;
7880
+ if (given["--sites"] !== undefined) {
7881
+ sites =
7882
+ given["--sites"] === "all" ? "all" : given["--sites"].split(",").map((id) => id.trim());
7883
+ if (sites !== "all" && sites.some((id) => !isValidSiteId(id)))
7884
+ throw new Error("--sites is all, or Site ids separated by commas.");
7885
+ }
7873
7886
  let expiresInDays;
7874
7887
  if (given["--expires"] !== undefined) {
7875
7888
  expiresInDays = Number(given["--expires"]);
@@ -7883,6 +7896,7 @@ async function execute(ws, argv, stdin) {
7883
7896
  const created = await ws.createApiKey({
7884
7897
  name,
7885
7898
  ...(groups.length ? { groups } : {}),
7899
+ ...(sites === undefined ? {} : { sites }),
7886
7900
  ...(expiresInDays === undefined ? {} : { expiresInDays }),
7887
7901
  });
7888
7902
  const k = created.apiKey;
@@ -7893,6 +7907,11 @@ async function execute(ws, argv, stdin) {
7893
7907
  `This is ${name}'s key; it is shown only now. Give it to the other system as a secret:`,
7894
7908
  ` Authorization: Bearer <key>, against ${created.url}`,
7895
7909
  `It acts as ${k.actor}${k.groups.length ? ` with the groups ${k.groups.join(", ")}` : " with no groups"}, under global/db/access.sql, until ${utcMinute(k.expiresAt)}.`,
7910
+ k.sites === "all"
7911
+ ? "It may call { api: true } server functions on every unrestricted Site."
7912
+ : k.sites.length
7913
+ ? `It may call { api: true } server functions on ${k.sites.join(", ")}.`
7914
+ : "It calls no server functions; --sites says which Sites it may.",
7896
7915
  ].join("\n"),
7897
7916
  created,
7898
7917
  );
package/connections.mjs CHANGED
@@ -9,7 +9,7 @@ export const MANAGED_DOMAIN = "ezship.dev";
9
9
  * The contract's compatibility number (ADR 0072): raised only by a change an older client cannot survive.
10
10
  * @type {typeof import("./connections.d.mts").CONTRACT}
11
11
  */
12
- export const CONTRACT = 1;
12
+ export const CONTRACT = 2;
13
13
  /**
14
14
  * The oldest client contract this release still serves; a Host answers an older one 426.
15
15
  * @type {typeof import("./connections.d.mts").OLDEST_CONTRACT}
Binary file
package/ez.mjs CHANGED
@@ -1019,7 +1019,8 @@ async function dev(creds, args, dir) {
1019
1019
  */
1020
1020
  function needsSite(cmd, args) {
1021
1021
  if (cmd === "site" && args[0] === "access") return true;
1022
- if (cmd === "audit" || cmd === "db" || cmd === "support" || cmd === "email") return false;
1022
+ if (cmd === "audit" || cmd === "db" || cmd === "support" || cmd === "email" || cmd === "key")
1023
+ return false;
1023
1024
  return !["instance", "builders", "builder", "users", "user", "site", "help", "asset"].includes(
1024
1025
  cmd,
1025
1026
  );
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ezship",
3
- "version": "0.1.14",
3
+ "version": "0.1.15",
4
4
  "description": "ez, the ezship command line. The same files as @ezship/cli.",
5
5
  "license": "Apache-2.0",
6
6
  "bin": {
package/types.d.mts CHANGED
@@ -683,14 +683,15 @@ export type ListenerEvent = {
683
683
  body?: string;
684
684
  };
685
685
  /**
686
- * An API Key as `ez key list` shows it (docs/adr/0119): never the key, only its first characters. `actor` is
687
- * what History records its writes as.
686
+ * An API Key as `ez key list` shows it (docs/adr/0119, docs/adr/0151): never the key, only its first characters.
687
+ * `actor` is what History records its writes as; `sites` is whose `{ api: true }` functions it may call.
688
688
  */
689
689
  export type ApiKey = {
690
690
  name: string;
691
691
  actor: string;
692
692
  prefix: string;
693
693
  groups: string[];
694
+ sites: "all" | string[];
694
695
  createdBy: string;
695
696
  createdAt: number;
696
697
  expiresAt: number;
@@ -698,8 +699,13 @@ export type ApiKey = {
698
699
  revokedAt: number | null;
699
700
  state: "active" | "expired" | "revoked";
700
701
  };
701
- export type ApiKeyInput = { name: string; groups?: string[]; expiresInDays?: number };
702
- /** A new API Key: `key` is shown this once and never stored. `url` is the Site API's door. */
702
+ export type ApiKeyInput = {
703
+ name: string;
704
+ groups?: string[];
705
+ sites?: "all" | string[];
706
+ expiresInDays?: number;
707
+ };
708
+ /** A new API Key: `key` is shown this once and never stored. `url` is the Data API's door. */
703
709
  export type CreatedApiKey = { apiKey: ApiKey; key: string; url: string };
704
710
  /** One global/schedules.json entry (ADRs 0076, 0136): run `global/jobs/<job>.ts` with `input` on a UTC `cron`. */
705
711
  export type ScheduleEntry = {