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 +2 -2
- package/commands.mjs +49 -30
- package/connections.mjs +1 -1
- package/editor-types.json.gz +0 -0
- package/ez.mjs +2 -1
- package/package.json +1 -1
- package/types.d.mts +10 -4
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
|
|
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
|
|
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
|
|
231
|
-
* `Authorization: Bearer ezk_
|
|
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
|
|
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").
|
|
244
|
-
export const
|
|
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
|
|
3924
|
-
listApiKeys: { method: "GET", path: `${
|
|
3925
|
-
createApiKey: { method: "POST", path: `${
|
|
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: `${
|
|
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
|
|
4783
|
-
const API_TOPIC = `The
|
|
4784
|
-
and write this
|
|
4785
|
-
An Admin creates an API Key in a terminal: \`ez key create warehouse
|
|
4786
|
-
prints the key (${API_KEY_PREFIX}...) once; give it to the
|
|
4787
|
-
or in Site code. \`ez key list\` shows every key
|
|
4788
|
-
|
|
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
|
|
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.
|
|
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]
|
|
4802
|
-
|
|
4803
|
-
|
|
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};
|
|
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
|
|
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
|
|
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
|
|
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"
|
|
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:
|
|
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 =
|
|
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}
|
package/editor-types.json.gz
CHANGED
|
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"
|
|
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
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.
|
|
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 = {
|
|
702
|
-
|
|
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 = {
|