@tryghost/app-sdk 0.1.0-alpha.6 → 0.1.0-alpha.8
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/README.md +125 -10
- package/build/backend.d.ts +1 -10
- package/build/backend.js +1 -108
- package/build/backend.js.map +1 -1
- package/build/bin.d.ts +1 -0
- package/build/bin.js +139 -0
- package/build/bin.js.map +1 -0
- package/build/chunks/manifest-CInTdKjI.d.ts +19 -0
- package/build/chunks/manifest-DX1GTozy.js +219 -0
- package/build/chunks/manifest-DX1GTozy.js.map +1 -0
- package/build/chunks/rules-_dou3jRF.js +159 -0
- package/build/chunks/rules-_dou3jRF.js.map +1 -0
- package/build/chunks/sign-BhNJAPta.js +1130 -0
- package/build/chunks/sign-BhNJAPta.js.map +1 -0
- package/build/index.js +2 -153
- package/build/index.js.map +1 -1
- package/build/tooling.d.ts +177 -0
- package/build/tooling.js +3 -0
- package/dist/app-sdk.js +1 -1
- package/package.json +11 -3
package/README.md
CHANGED
|
@@ -1,18 +1,20 @@
|
|
|
1
1
|
# @tryghost/app-sdk
|
|
2
2
|
|
|
3
|
-
The SDK apps use to talk to Ghost: from their page inside Admin,
|
|
4
|
-
backend.
|
|
3
|
+
The SDK apps use to talk to Ghost: from their page inside Admin, from their
|
|
4
|
+
backend, and from their tooling.
|
|
5
5
|
|
|
6
6
|
An app's page runs in a frame inside Ghost Admin. The SDK connects it to Admin,
|
|
7
7
|
gives it the site, the user and the theme, and lets it call the Admin API, keep
|
|
8
8
|
its route in sync with Admin's URL, and send the publisher elsewhere in Admin.
|
|
9
9
|
|
|
10
|
-
| Entry point | Runs in | What it's for
|
|
11
|
-
| --------------------------- | -------------------------- |
|
|
12
|
-
| `@tryghost/app-sdk` | The app's page | Talking to Admin (below)
|
|
13
|
-
| `@tryghost/app-sdk/backend` | Any platform with web APIs | [Answering Ghost's challenge and serving the manifest](#the-backend)
|
|
10
|
+
| Entry point | Runs in | What it's for |
|
|
11
|
+
| --------------------------- | -------------------------- | ----------------------------------------------------------------------------- |
|
|
12
|
+
| `@tryghost/app-sdk` | The app's page | Talking to Admin (below) |
|
|
13
|
+
| `@tryghost/app-sdk/backend` | Any platform with web APIs | [Answering Ghost's challenge and serving the manifest](#the-backend) |
|
|
14
|
+
| `@tryghost/app-sdk/tooling` | Node 22.12 or later | [Creating keys, and signing and checking the manifest](#signing-the-manifest) |
|
|
15
|
+
| `ghost-app` | Node 22.12 or later | [The same tooling on the command line](#the-ghost-app-cli) |
|
|
14
16
|
|
|
15
|
-
The page's entry point loads none of the
|
|
17
|
+
The page's entry point loads none of the others' code.
|
|
16
18
|
|
|
17
19
|
> **Alpha.** CI publishes each change to npm as the next `0.1.0-alpha.N` under
|
|
18
20
|
> the `latest` tag. Alphas make no compatibility promise.
|
|
@@ -260,6 +262,117 @@ documents in a row, each replaced within three seconds of starting. A publisher
|
|
|
260
262
|
clicking quickly through more than five pages of a multi-page app would trip it
|
|
261
263
|
too.
|
|
262
264
|
|
|
265
|
+
## Signing the manifest
|
|
266
|
+
|
|
267
|
+
Ghost installs an app from its manifest URL, where the app serves a signed
|
|
268
|
+
manifest: its `ghost-app.json`, with the fields below added, signed with the
|
|
269
|
+
app's identity key. Ghost pins that key when a site installs the app, and
|
|
270
|
+
challenges the app's origin to prove it holds the backend key the manifest
|
|
271
|
+
names. The manifest format is in
|
|
272
|
+
[`@tryghost/app-contracts`](../app-contracts/README.md#the-manifest).
|
|
273
|
+
|
|
274
|
+
`ghost-app.json` is the readable part, which the project keeps:
|
|
275
|
+
|
|
276
|
+
```json
|
|
277
|
+
{
|
|
278
|
+
"id": "com.example.hello",
|
|
279
|
+
"name": "Hello",
|
|
280
|
+
"description": "Says hello.",
|
|
281
|
+
"author": { "name": "Example", "url": "https://example.com" },
|
|
282
|
+
"accent_color": "#ff5500",
|
|
283
|
+
"icon": { "name": "hand" },
|
|
284
|
+
"surfaces": [{ "type": "admin_page", "url": "/" }]
|
|
285
|
+
}
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
Signing adds `manifest_url` (the address it's signed for), `identity_key` and
|
|
289
|
+
`backend_key` (the public keys) and `development`, and refuses a file that sets
|
|
290
|
+
any of them. It checks the manifest with the rules Ghost applies first, so a
|
|
291
|
+
manifest Ghost would refuse is never signed: the error lists every problem by
|
|
292
|
+
field. Ghost also refuses a manifest on the site's or Admin's host, on any port,
|
|
293
|
+
which only Ghost knows.
|
|
294
|
+
|
|
295
|
+
### Keys
|
|
296
|
+
|
|
297
|
+
Each mode has its own identity key and backend key, as two pairs of private
|
|
298
|
+
Ed25519 JWKs, in files only their owner can read:
|
|
299
|
+
|
|
300
|
+
- `.ghost-app/development/identity.json` and `backend.json`, for apps on this
|
|
301
|
+
machine, such as on `my-app.localhost`, which `ghost-app keys` creates;
|
|
302
|
+
- `.ghost-app/production/identity.json` and `backend.json`, which only
|
|
303
|
+
`ghost-app keys --production` creates.
|
|
304
|
+
|
|
305
|
+
Only the owner can read a key on macOS and Linux. On Windows, a key gets the
|
|
306
|
+
permissions of the folder it's in, so keep the project in a folder only you can
|
|
307
|
+
read.
|
|
308
|
+
|
|
309
|
+
Keys are created only when git ignores `.ghost-app/` (in a repository), and an
|
|
310
|
+
existing key is never replaced. Keep a copy of the production identity key
|
|
311
|
+
somewhere safe: sites keep the identity key they installed an app with, and a
|
|
312
|
+
manifest signed with another one is another app. A development installation
|
|
313
|
+
and a production one are different apps for the same reason, so going from your
|
|
314
|
+
computer to a host means installing the app again.
|
|
315
|
+
|
|
316
|
+
The identity key stays with the developer, or CI. It never reaches the backend
|
|
317
|
+
or a build: only the signed manifest is served or emitted. The backend key goes
|
|
318
|
+
to the backend, which answers challenges with it. Developers who share a
|
|
319
|
+
development identity key must share its backend key too: a new backend key
|
|
320
|
+
retires the old one on every site that reads the new manifest.
|
|
321
|
+
|
|
322
|
+
In CI, set `GHOST_APP_IDENTITY_KEY` to the production identity key and
|
|
323
|
+
`GHOST_APP_BACKEND_KEY` to the backend key's public half, which
|
|
324
|
+
`ghost-app backend-key --production --public` prints, in place of the files. CI
|
|
325
|
+
only signs, so it never needs the backend's private key.
|
|
326
|
+
|
|
327
|
+
### The ghost-app CLI
|
|
328
|
+
|
|
329
|
+
```sh
|
|
330
|
+
ghost-app keys [--production]
|
|
331
|
+
ghost-app sign --url <manifest URL> [--production] [--out <file>] [--manifest <file>]
|
|
332
|
+
ghost-app check <manifest URL>
|
|
333
|
+
ghost-app backend-key [--production] [--public | --check]
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
- `keys` creates the mode's keys, keeping any that exist.
|
|
337
|
+
- `sign` prints the signed manifest, or writes it to `--out`.
|
|
338
|
+
- `check` checks an app as Ghost does before installing it, with `checkApp`
|
|
339
|
+
(below), and prints Ghost's own code and what exactly was wrong.
|
|
340
|
+
- `backend-key` prints the mode's private backend key, for a host's secret
|
|
341
|
+
store. It's the only command that prints a private key. `--public` prints
|
|
342
|
+
only its public half, for CI. `--check` prints nothing, and exits with 0
|
|
343
|
+
only if the key is there and usable, with the reason on stderr otherwise,
|
|
344
|
+
so a script can stop before piping nothing into a secret store, in any shell:
|
|
345
|
+
|
|
346
|
+
```sh
|
|
347
|
+
ghost-app backend-key --production --check && ghost-app backend-key --production | wrangler secret put GHOST_APP_BACKEND_KEY
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
`--dir` points any of them at another project directory.
|
|
351
|
+
|
|
352
|
+
### From code
|
|
353
|
+
|
|
354
|
+
`@tryghost/app-sdk/tooling` is what the CLI is built on, to sign and check from code:
|
|
355
|
+
|
|
356
|
+
| Export | What it does |
|
|
357
|
+
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
358
|
+
| `createKeys({ root, mode })` | Creates the mode's missing keys. Resolves with `{ created, kept }`. |
|
|
359
|
+
| `readSigningKeys({ root, mode, env? })` | The identity key and the backend key's public half, from the files or, in production, `env`. |
|
|
360
|
+
| `readBackendKey({ root, mode })` | The mode's private backend key. |
|
|
361
|
+
| `signProject({ root, mode, manifestUrl, manifestFile? })` | Signs the project's `ghost-app.json` with the mode's keys. |
|
|
362
|
+
| `signAppManifest(source, { manifestUrl, identityKey, backendKey, development })` | Signs a manifest with the keys given. |
|
|
363
|
+
| `checkApp(manifestUrl, { fetch? })` | Checks an app as Ghost does before installing it. Resolves with the parsed manifest, or a failure with Ghost's code. |
|
|
364
|
+
| `generateKey()`, `publicKeyOf(key)` | A new private key, and a key's public half. |
|
|
365
|
+
|
|
366
|
+
Signing resolves with `{ success: true, signed, manifest }`, or
|
|
367
|
+
`{ success: false, code, errors }`.
|
|
368
|
+
|
|
369
|
+
`checkApp` fetches the signed manifest, verifies it, and challenges the app's
|
|
370
|
+
origin, even on `localhost`, which Ghost in development doesn't. A failure
|
|
371
|
+
carries Ghost's own code, such as `APP_MANIFEST_URL_MISMATCH`,
|
|
372
|
+
`APP_MANIFEST_SIGNATURE_INVALID` or `APP_CHALLENGE_FAILED`, and what exactly was
|
|
373
|
+
wrong. It can't check what only a site knows: the key it installed the app
|
|
374
|
+
with, and backend keys a newer manifest replaced.
|
|
375
|
+
|
|
263
376
|
## The backend
|
|
264
377
|
|
|
265
378
|
`@tryghost/app-sdk/backend` uses only `Request`, `Response`, `fetch` and
|
|
@@ -332,7 +445,7 @@ This is a workspace package in the Ghost monorepo. From the package directory:
|
|
|
332
445
|
```bash
|
|
333
446
|
pnpm build # the package to build/ and the browser bundle to dist/, with Vite
|
|
334
447
|
pnpm test # type-check + unit tests (jsdom for the page, with a fake Admin on a real
|
|
335
|
-
# MessageChannel; Node for the backend), which build both
|
|
448
|
+
# MessageChannel; Node for the backend, tooling and CLI), which build both
|
|
336
449
|
# afresh to check what they import, and pack build/ and dist/ to use them from an
|
|
337
450
|
# app outside the workspace (after pnpm build; Nx runs it)
|
|
338
451
|
pnpm lint # lint source and tests
|
|
@@ -344,14 +457,16 @@ and also writes `dist/`, which is in `files` and in the Nx build outputs.
|
|
|
344
457
|
|
|
345
458
|
It uses `@tryghost/app-contracts` for the bridge's message types, limits and
|
|
346
459
|
shape checks, so the SDK and Admin apply the same rules to paths, themes and
|
|
347
|
-
start contexts, and for
|
|
348
|
-
own rules. The build inlines what it uses
|
|
460
|
+
start contexts, and for signing and checking manifests and challenges, so the
|
|
461
|
+
tooling and the backend apply Ghost's own rules. The build inlines what it uses
|
|
349
462
|
into the SDK, so the contracts are a dev dependency. `build/` has an ES module
|
|
350
463
|
per entry point, which share chunks:
|
|
351
464
|
|
|
352
465
|
- `index.js` loads only `@quilted/threads`, never `jose`, `zod` or a Node
|
|
353
466
|
builtin;
|
|
354
467
|
- `backend.js` loads only `jose` and `zod`, and no Node builtin;
|
|
468
|
+
- `tooling.js` loads Node builtins, `jose` and `zod`, and `bin.js` those and
|
|
469
|
+
`commander`;
|
|
355
470
|
- each entry point's declarations, emitted by TypeScript 7 and bundled by
|
|
356
471
|
`rolldown-plugin-dts`, import nothing;
|
|
357
472
|
- `dist/` imports nothing at all.
|
package/build/backend.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { r as SignedManifest, t as MANIFEST_PATH } from "./chunks/manifest-CInTdKjI.js";
|
|
1
2
|
//#region ../app-contracts/build/identity/challenge.d.ts
|
|
2
3
|
/** Where on an origin Ghost posts a challenge. */
|
|
3
4
|
declare const CHALLENGE_PATH = "/.well-known/ghost-app/challenge";
|
|
@@ -75,16 +76,6 @@ declare function withGhostApp<Args extends unknown[] = []>({ fetch, ...challenge
|
|
|
75
76
|
fetch: (request: Request, ...args: Args) => Promise<Response>;
|
|
76
77
|
};
|
|
77
78
|
//#endregion
|
|
78
|
-
//#region src/shared/manifest.d.ts
|
|
79
|
-
/** Where an app serves its signed manifest by convention, and where the SDK's tooling signs it for. */
|
|
80
|
-
declare const MANIFEST_PATH = "/ghost-app.json";
|
|
81
|
-
/** A signed manifest: flattened JWS JSON, as `ghost-app sign` or the Vite plugin writes it. */
|
|
82
|
-
interface SignedManifest {
|
|
83
|
-
protected: string;
|
|
84
|
-
payload: string;
|
|
85
|
-
signature: string;
|
|
86
|
-
}
|
|
87
|
-
//#endregion
|
|
88
79
|
//#region src/backend/manifest.d.ts
|
|
89
80
|
/**
|
|
90
81
|
* A response that serves the signed manifest, for a backend that doesn't serve it as a static
|
package/build/backend.js
CHANGED
|
@@ -1,107 +1,4 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { z } from "zod";
|
|
3
|
-
//#region ../app-contracts/build/identity/jws.js
|
|
4
|
-
/** The only algorithm either key signs with. */
|
|
5
|
-
var ALGORITHM = "Ed25519";
|
|
6
|
-
//#endregion
|
|
7
|
-
//#region ../app-contracts/build/identity/challenge.js
|
|
8
|
-
/** Where on an origin Ghost posts a challenge. */
|
|
9
|
-
var CHALLENGE_PATH = "/.well-known/ghost-app/challenge";
|
|
10
|
-
/** What a challenge is for, signed with it, so its answer can't pass for any other signature. */
|
|
11
|
-
var CHALLENGE_PURPOSE = "ghost-app-challenge";
|
|
12
|
-
z.strictObject({ alg: z.literal(ALGORITHM) });
|
|
13
|
-
JSON.stringify({ alg: ALGORITHM });
|
|
14
|
-
var ChallengeShape = z.strictObject({
|
|
15
|
-
purpose: z.literal(CHALLENGE_PURPOSE),
|
|
16
|
-
origin: z.string(),
|
|
17
|
-
nonce: z.string()
|
|
18
|
-
});
|
|
19
|
-
z.object({ signature: z.string() });
|
|
20
|
-
/**
|
|
21
|
-
* Answers a challenge a backend received, signing it with the backend key. `requestUrl` is
|
|
22
|
-
* the URL the request arrived at, as the platform reports it (`request.url` on Workers):
|
|
23
|
-
* never one built from `X-Forwarded-Host` or any other header the sender controls. A
|
|
24
|
-
* challenge for any origin but that one is refused, so whoever takes over a name the app
|
|
25
|
-
* used to serve can't relay Ghost's challenge to the real backend to prove it.
|
|
26
|
-
*
|
|
27
|
-
* Ghost can't see this check, so it only helps where the platform routes requests by host,
|
|
28
|
-
* as Workers, Vercel, Netlify and Fly do. A server that answers for any host gains nothing.
|
|
29
|
-
*/
|
|
30
|
-
async function answerChallenge(body, { backendKey, requestUrl }) {
|
|
31
|
-
const challenge = ChallengeShape.safeParse(parseJson(body));
|
|
32
|
-
if (!challenge.success) return {
|
|
33
|
-
success: false,
|
|
34
|
-
error: "Expected a challenge of {purpose, origin, nonce}"
|
|
35
|
-
};
|
|
36
|
-
const arrivedAt = URL.parse(requestUrl)?.origin;
|
|
37
|
-
if (arrivedAt !== challenge.data.origin) return {
|
|
38
|
-
success: false,
|
|
39
|
-
error: `The challenge is for ${challenge.data.origin}, but arrived at ${arrivedAt ?? "an unknown origin"}`
|
|
40
|
-
};
|
|
41
|
-
return {
|
|
42
|
-
success: true,
|
|
43
|
-
answer: { signature: await new CompactSign(new TextEncoder().encode(body)).setProtectedHeader({ alg: ALGORITHM }).sign(backendKey) }
|
|
44
|
-
};
|
|
45
|
-
}
|
|
46
|
-
function parseJson(text) {
|
|
47
|
-
try {
|
|
48
|
-
return JSON.parse(text);
|
|
49
|
-
} catch {
|
|
50
|
-
return;
|
|
51
|
-
}
|
|
52
|
-
}
|
|
53
|
-
//#endregion
|
|
54
|
-
//#region src/shared/parse.ts
|
|
55
|
-
var UNSAFE_IN_POLICY = /[\s;,'"*]/;
|
|
56
|
-
/**
|
|
57
|
-
* An HTTP or HTTPS origin, or `undefined` for anything more or less. The URL parser lets `;` and
|
|
58
|
-
* `,` into a host, so the origin must also read back as itself, and hold nothing that would end
|
|
59
|
-
* a source in a Content-Security-Policy.
|
|
60
|
-
*/
|
|
61
|
-
function parseOrigin(entry) {
|
|
62
|
-
const url = URL.parse(entry);
|
|
63
|
-
const origin = url?.origin;
|
|
64
|
-
if (!url || !origin || url.protocol !== "https:" && url.protocol !== "http:" || url.href !== `${origin}/` || URL.parse(origin)?.origin !== origin || UNSAFE_IN_POLICY.test(entry) || UNSAFE_IN_POLICY.test(origin)) return;
|
|
65
|
-
return origin;
|
|
66
|
-
}
|
|
67
|
-
//#endregion
|
|
68
|
-
//#region src/shared/ignore.ts
|
|
69
|
-
/** For an error that changes nothing, such as one from cancelling what's no longer wanted. */
|
|
70
|
-
var ignoreError = () => void 0;
|
|
71
|
-
//#endregion
|
|
72
|
-
//#region src/shared/body.ts
|
|
73
|
-
/**
|
|
74
|
-
* Reads a request's or a response's body, or `undefined` if it is longer than `maxBytes`. It
|
|
75
|
-
* stops reading as soon as the body passes the limit, so a large body is never held whole.
|
|
76
|
-
*/
|
|
77
|
-
async function readBytes(message, maxBytes) {
|
|
78
|
-
if (Number(message.headers.get("content-length")) > maxBytes) {
|
|
79
|
-
message.body?.cancel().catch(ignoreError);
|
|
80
|
-
return;
|
|
81
|
-
}
|
|
82
|
-
if (!message.body) return /* @__PURE__ */ new Uint8Array();
|
|
83
|
-
const reader = message.body.getReader();
|
|
84
|
-
const chunks = [];
|
|
85
|
-
let length = 0;
|
|
86
|
-
for (;;) {
|
|
87
|
-
const { done, value } = await reader.read();
|
|
88
|
-
if (done) break;
|
|
89
|
-
length += value.byteLength;
|
|
90
|
-
if (length > maxBytes) {
|
|
91
|
-
reader.cancel().catch(ignoreError);
|
|
92
|
-
return;
|
|
93
|
-
}
|
|
94
|
-
chunks.push(value);
|
|
95
|
-
}
|
|
96
|
-
const bytes = new Uint8Array(length);
|
|
97
|
-
let offset = 0;
|
|
98
|
-
for (const chunk of chunks) {
|
|
99
|
-
bytes.set(chunk, offset);
|
|
100
|
-
offset += chunk.byteLength;
|
|
101
|
-
}
|
|
102
|
-
return bytes;
|
|
103
|
-
}
|
|
104
|
-
//#endregion
|
|
1
|
+
import { c as CHALLENGE_PATH, i as readBytes, l as answerChallenge, s as parseOrigin, t as MANIFEST_PATH } from "./chunks/manifest-DX1GTozy.js";
|
|
105
2
|
//#region src/backend/body.ts
|
|
106
3
|
/**
|
|
107
4
|
* Reads a request's body as UTF-8 text, or `undefined` if it is longer than `maxBytes`. Invalid
|
|
@@ -201,10 +98,6 @@ function withGhostApp({ fetch, ...challenge }) {
|
|
|
201
98
|
} };
|
|
202
99
|
}
|
|
203
100
|
//#endregion
|
|
204
|
-
//#region src/shared/manifest.ts
|
|
205
|
-
/** Where an app serves its signed manifest by convention, and where the SDK's tooling signs it for. */
|
|
206
|
-
var MANIFEST_PATH = "/ghost-app.json";
|
|
207
|
-
//#endregion
|
|
208
101
|
//#region src/backend/manifest.ts
|
|
209
102
|
/**
|
|
210
103
|
* A response that serves the signed manifest, for a backend that doesn't serve it as a static
|
package/build/backend.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"backend.js","names":[],"sources":["../../app-contracts/build/identity/jws.js","../../app-contracts/build/identity/challenge.js","../src/shared/parse.ts","../src/shared/ignore.ts","../src/shared/body.ts","../src/backend/body.ts","../src/backend/challenge.ts","../src/backend/app.ts","../src/shared/manifest.ts","../src/backend/manifest.ts"],"sourcesContent":["import { decodeJson } from './keys.js';\n/** The only algorithm either key signs with. */\nexport const ALGORITHM = 'Ed25519';\n/**\n * Reads a JWS protected header that must be exactly `shape`, which is a strict object. Any\n * other member could change what the signature covers, as `b64: false` does, or name\n * another key, so the header is checked before the signature and again when verifying.\n */\nexport function readExactHeader(encoded, shape) {\n const parsed = shape.safeParse(decodeJson(encoded));\n return parsed.success ? parsed.data : undefined;\n}\n//# sourceMappingURL=jws.js.map","import { CompactSign, base64url, compactVerify, importJWK } from 'jose';\nimport { z } from 'zod';\nimport { ALGORITHM, readExactHeader } from './jws.js';\nimport { decodeUtf8 } from './keys.js';\n/** Where on an origin Ghost posts a challenge. */\nexport const CHALLENGE_PATH = '/.well-known/ghost-app/challenge';\n/** What a challenge is for, signed with it, so its answer can't pass for any other signature. */\nexport const CHALLENGE_PURPOSE = 'ghost-app-challenge';\nconst NONCE_BYTES = 32;\nconst ProtectedHeader = z.strictObject({ alg: z.literal(ALGORITHM) });\nconst EXPECTED_HEADER = JSON.stringify({ alg: ALGORITHM });\nconst ChallengeShape = z.strictObject({\n purpose: z.literal(CHALLENGE_PURPOSE),\n origin: z.string(),\n nonce: z.string(),\n});\nconst ChallengeAnswerShape = z.object({ signature: z.string() });\n/** The URL to post a challenge for an origin to. */\nexport function challengeUrl(origin) {\n return new URL(CHALLENGE_PATH, origin).href;\n}\n/** A fresh challenge for an origin, as the exact text to post and to verify the answer with. */\nexport function createChallenge(origin) {\n const challenge = {\n purpose: CHALLENGE_PURPOSE,\n origin: new URL(origin).origin,\n nonce: base64url.encode(crypto.getRandomValues(new Uint8Array(NONCE_BYTES))),\n };\n return JSON.stringify(challenge);\n}\n/**\n * Answers a challenge a backend received, signing it with the backend key. `requestUrl` is\n * the URL the request arrived at, as the platform reports it (`request.url` on Workers):\n * never one built from `X-Forwarded-Host` or any other header the sender controls. A\n * challenge for any origin but that one is refused, so whoever takes over a name the app\n * used to serve can't relay Ghost's challenge to the real backend to prove it.\n *\n * Ghost can't see this check, so it only helps where the platform routes requests by host,\n * as Workers, Vercel, Netlify and Fly do. A server that answers for any host gains nothing.\n */\nexport async function answerChallenge(body, { backendKey, requestUrl }) {\n const challenge = ChallengeShape.safeParse(parseJson(body));\n if (!challenge.success) {\n return { success: false, error: 'Expected a challenge of {purpose, origin, nonce}' };\n }\n const arrivedAt = URL.parse(requestUrl)?.origin;\n if (arrivedAt !== challenge.data.origin) {\n return {\n success: false,\n error: `The challenge is for ${challenge.data.origin}, but arrived at ${arrivedAt ?? 'an unknown origin'}`,\n };\n }\n const signature = await new CompactSign(new TextEncoder().encode(body))\n .setProtectedHeader({ alg: ALGORITHM })\n .sign(backendKey);\n return { success: true, answer: { signature } };\n}\n/**\n * Checks an origin's answer to a challenge: a signature with the backend key over the\n * exact text Ghost posted, under a protected header of only `alg`. The error only says how\n * the answer fell short.\n */\nexport async function verifyChallengeAnswer(challenge, answer, backendKey) {\n const parsed = ChallengeAnswerShape.safeParse(parseJson(answer));\n if (!parsed.success) {\n return { success: false, error: 'Expected an answer of {\"signature\": \"<compact JWS>\"}' };\n }\n let key;\n try {\n key = await importJWK(backendKey, ALGORITHM);\n }\n catch {\n return { success: false, error: 'backend_key is not a usable Ed25519 key' };\n }\n const [header = ''] = parsed.data.signature.split('.');\n if (!readExactHeader(header, ProtectedHeader)) {\n return { success: false, error: `Expected a protected header of ${EXPECTED_HEADER}` };\n }\n let payload;\n try {\n ({ payload } = await compactVerify(parsed.data.signature, key, { algorithms: [ALGORITHM] }));\n }\n catch {\n return { success: false, error: 'The signature was not made with backend_key' };\n }\n if (!sameText(payload, challenge)) {\n return { success: false, error: 'The signature is not over the challenge that was sent' };\n }\n return { success: true };\n}\nfunction sameText(bytes, text) {\n try {\n return decodeUtf8(bytes) === text;\n }\n catch {\n return false;\n }\n}\nfunction parseJson(text) {\n try {\n return JSON.parse(text);\n }\n catch {\n return undefined;\n }\n}\n//# sourceMappingURL=challenge.js.map","// Characters that end a source in a policy, a directive or a whole policy, and the wildcard.\nconst UNSAFE_IN_POLICY = /[\\s;,'\"*]/;\n\n/**\n * An HTTP or HTTPS origin, or `undefined` for anything more or less. The URL parser lets `;` and\n * `,` into a host, so the origin must also read back as itself, and hold nothing that would end\n * a source in a Content-Security-Policy.\n */\nexport function parseOrigin(entry: string): string | undefined {\n const url = URL.parse(entry);\n const origin = url?.origin;\n if (\n !url ||\n !origin ||\n (url.protocol !== 'https:' && url.protocol !== 'http:') ||\n url.href !== `${origin}/` ||\n URL.parse(origin)?.origin !== origin ||\n UNSAFE_IN_POLICY.test(entry) ||\n UNSAFE_IN_POLICY.test(origin)\n ) {\n return undefined;\n }\n return origin;\n}\n","/** For an error that changes nothing, such as one from cancelling what's no longer wanted. */\nexport const ignoreError = (): undefined => undefined;\n","import { ignoreError } from './ignore.ts';\n\n/**\n * Reads a request's or a response's body, or `undefined` if it is longer than `maxBytes`. It\n * stops reading as soon as the body passes the limit, so a large body is never held whole.\n */\nexport async function readBytes(\n message: Request | Response,\n maxBytes: number,\n): Promise<Uint8Array | undefined> {\n if (Number(message.headers.get('content-length')) > maxBytes) {\n // Too large either way, so a body that refuses to be cancelled changes nothing. Not waited\n // for: one branch of a teed body, as a cloned request's is, cancels only once the other does.\n message.body?.cancel().catch(ignoreError);\n return undefined;\n }\n if (!message.body) {\n return new Uint8Array();\n }\n const reader = message.body.getReader();\n const chunks: Uint8Array[] = [];\n let length = 0;\n for (;;) {\n const { done, value } = await reader.read();\n if (done) {\n break;\n }\n length += value.byteLength;\n if (length > maxBytes) {\n reader.cancel().catch(ignoreError);\n return undefined;\n }\n chunks.push(value);\n }\n const bytes = new Uint8Array(length);\n let offset = 0;\n for (const chunk of chunks) {\n bytes.set(chunk, offset);\n offset += chunk.byteLength;\n }\n return bytes;\n}\n","import { readBytes } from '../shared/body.ts';\n\n/**\n * Reads a request's body as UTF-8 text, or `undefined` if it is longer than `maxBytes`. Invalid\n * UTF-8 throws, as the exact text matters to whoever signs it.\n */\nexport async function readText(request: Request, maxBytes: number): Promise<string | undefined> {\n const bytes = await readBytes(request, maxBytes);\n return bytes && new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);\n}\n\nexport function json(status: number, body: unknown, headers: Record<string, string> = {}) {\n return new Response(JSON.stringify(body), {\n status,\n headers: {\n 'content-type': 'application/json; charset=utf-8',\n 'cache-control': 'no-store',\n ...headers,\n },\n });\n}\n","import { CHALLENGE_PATH, answerChallenge } from '@tryghost/app-contracts/identity';\n\nimport { parseOrigin } from '../shared/parse.ts';\nimport { json, readText } from './body.ts';\n\nexport { CHALLENGE_PATH };\n\n/**\n * A JWK, with the members RFC 7517 and RFC 7518 name. It's the package's own, as the DOM's\n * `JsonWebKey` doesn't exist in a backend that types against Node without the DOM library, and\n * a type alias rather than an interface, so a DOM `JsonWebKey` or a jose `JWK` passes for it.\n */\nexport type BackendJwk = {\n alg?: string;\n crv?: string;\n d?: string;\n dp?: string;\n dq?: string;\n e?: string;\n ext?: boolean;\n k?: string;\n key_ops?: string[];\n kid?: string;\n kty?: string;\n n?: string;\n oth?: { d?: string; r?: string; t?: string }[];\n p?: string;\n q?: string;\n qi?: string;\n use?: string;\n x?: string;\n y?: string;\n};\n\n/**\n * The backend key's private half: a JWK object, or its JSON as it sits in a secret or an\n * environment variable, such as `GHOST_APP_BACKEND_KEY`.\n */\nexport type BackendKey = BackendJwk | string;\n\nexport interface HandleChallengeOptions {\n backendKey: BackendKey;\n /**\n * The app's public origin, such as `https://app.example.com`, for a server that doesn't see\n * the scheme and host Ghost reaches it at, as Node behind a proxy that terminates TLS sees\n * `http://`. Ghost challenges the public origin, so without it every challenge is refused.\n * Take it from the app's own configuration, never from a request's headers, which the sender\n * sets. Workers, and other platforms that report the public URL, don't need it.\n */\n origin?: string;\n}\n\n// Ghost's challenge is about 150 bytes. Anything much larger isn't one.\nconst CHALLENGE_MAX_BYTES = 4 * 1024;\n\nconst INVALID_KEY =\n 'backendKey must be a private Ed25519 key as a JWK, with kty \"OKP\", crv \"Ed25519\", x and d';\n\n// The last key imported, so a backend that answers with one key imports it once.\nlet imported: { text: string; key: Promise<CryptoKey> } | undefined;\n\nfunction importBackendKey(backendKey: BackendKey): Promise<CryptoKey> {\n const text = typeof backendKey === 'string' ? backendKey : JSON.stringify(backendKey);\n if (imported?.text !== text) {\n const key = importPrivateKey(text);\n imported = { text, key };\n // A key that failed to import is tried again next time, so a fixed secret takes effect.\n key.catch(() => {\n if (imported?.key === key) {\n imported = undefined;\n }\n });\n }\n return imported.key;\n}\n\nasync function importPrivateKey(text: string): Promise<CryptoKey> {\n let jwk: unknown;\n try {\n jwk = JSON.parse(text);\n } catch {\n // Never says what the text was: it's a secret.\n throw new TypeError(`${INVALID_KEY}; it isn't JSON`);\n }\n const { kty, crv, x, d } = (typeof jwk === 'object' && jwk !== null ? jwk : {}) as BackendJwk;\n if (kty !== 'OKP' || crv !== 'Ed25519' || typeof x !== 'string' || typeof d !== 'string') {\n throw new TypeError(INVALID_KEY);\n }\n try {\n return await crypto.subtle.importKey('jwk', { kty, crv, x, d }, { name: 'Ed25519' }, false, [\n 'sign',\n ]);\n } catch (error) {\n throw new TypeError(INVALID_KEY, { cause: error });\n }\n}\n\n/**\n * Answers Ghost's challenge by signing it with the backend key. Route only `CHALLENGE_PATH`\n * to it, or use `withGhostApp`, which does.\n */\nexport async function handleChallenge(\n request: Request,\n { backendKey, origin }: HandleChallengeOptions,\n): Promise<Response> {\n // A bad `origin` is the app's own misconfiguration, so it throws, and the platform reports a\n // server error, rather than every challenge being refused with a 400 that looks like Ghost's\n // fault.\n const publicOrigin = origin === undefined ? undefined : parseOrigin(origin);\n if (origin !== undefined && !publicOrigin) {\n throw new TypeError(\n `Expected origin to be the app's origin, such as https://app.example.com, not ${origin}`,\n );\n }\n\n // Ghost always POSTs the challenge.\n if (request.method !== 'POST') {\n return json(405, { error: 'Expected a POST' }, { allow: 'POST' });\n }\n\n // A challenge is about 150 bytes, so stop reading at 4 KB rather than buffer whatever a\n // sender streams.\n let body: string | undefined;\n try {\n body = await readText(request, CHALLENGE_MAX_BYTES);\n } catch {\n return json(400, { error: 'Expected a challenge in UTF-8' });\n }\n if (body === undefined) {\n return json(413, { error: `Expected a challenge of at most ${CHALLENGE_MAX_BYTES} bytes` });\n }\n\n // Imported once and cached. A `backendKey` that isn't a private Ed25519 key throws a\n // `TypeError`, a server error, for the same reason as a bad `origin`.\n const key = await importBackendKey(backendKey);\n\n // The challenge names the origin Ghost sent it to, and is answered only for this app's own:\n // the one the platform reports in `request.url`, or `origin` behind a proxy. Never one taken\n // from `X-Forwarded-Host` or another header the sender sets, or anyone could have this\n // backend sign a challenge meant for another app.\n const result = await answerChallenge(body, {\n backendKey: key,\n requestUrl: publicOrigin ?? request.url,\n });\n if (!result.success) {\n return json(400, { error: result.error });\n }\n\n // `{ signature }`: Ghost verifies it against the backend key the signed manifest names.\n return json(200, result.answer);\n}\n","import { CHALLENGE_PATH, handleChallenge, type HandleChallengeOptions } from './challenge.ts';\n\n/**\n * A fetch handler: the request, then whatever else the platform passes, such as a Worker's `env`\n * and `ctx`.\n */\nexport type FetchHandler<Args extends unknown[] = []> = (\n request: Request,\n ...args: Args\n) => Response | Promise<Response>;\n\nexport interface GhostAppOptions<Args extends unknown[] = []> extends HandleChallengeOptions {\n /** The app's own handler, for every request but Ghost's challenge. */\n fetch: FetchHandler<Args>;\n}\n\n/**\n * The app's backend: answers Ghost's challenge at `CHALLENGE_PATH` with `handleChallenge`, and\n * passes every other request to `fetch`, with whatever else the platform passes.\n *\n * It returns `{ fetch }`, so a Worker can export it as it is, and Bun can serve it.\n */\nexport function withGhostApp<Args extends unknown[] = []>({\n fetch,\n ...challenge\n}: GhostAppOptions<Args>): { fetch: (request: Request, ...args: Args) => Promise<Response> } {\n return {\n async fetch(request, ...args) {\n if (new URL(request.url).pathname === CHALLENGE_PATH) {\n return handleChallenge(request, challenge);\n }\n return fetch(request, ...args);\n },\n };\n}\n","// What the backend, the tooling and the Vite plugin agree on about the signed manifest. Free of\n// Node and of the contracts' validation, as the backend runs on any platform.\n\n/** Where an app serves its signed manifest by convention, and where the SDK's tooling signs it for. */\nexport const MANIFEST_PATH = '/ghost-app.json';\n\n/** A signed manifest: flattened JWS JSON, as `ghost-app sign` or the Vite plugin writes it. */\nexport interface SignedManifest {\n protected: string;\n payload: string;\n signature: string;\n}\n","import type { SignedManifest } from '../shared/manifest.ts';\n\nexport { MANIFEST_PATH, type SignedManifest } from '../shared/manifest.ts';\n\n/**\n * A response that serves the signed manifest, for a backend that doesn't serve it as a static\n * file. Pass the file's text as it is, or the object it holds.\n *\n * Caches may keep it, but must check it's still current each time, so a new manifest reaches\n * Ghost the next time Ghost reads it.\n */\nexport function serveManifest(signed: SignedManifest | string): Response {\n return new Response(typeof signed === 'string' ? signed : JSON.stringify(signed), {\n headers: {\n 'content-type': 'application/json; charset=utf-8',\n 'cache-control': 'no-cache',\n },\n });\n}\n"],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"backend.js","names":[],"sources":["../src/backend/body.ts","../src/backend/challenge.ts","../src/backend/app.ts","../src/backend/manifest.ts"],"sourcesContent":["import { readBytes } from '../shared/body.ts';\n\n/**\n * Reads a request's body as UTF-8 text, or `undefined` if it is longer than `maxBytes`. Invalid\n * UTF-8 throws, as the exact text matters to whoever signs it.\n */\nexport async function readText(request: Request, maxBytes: number): Promise<string | undefined> {\n const bytes = await readBytes(request, maxBytes);\n return bytes && new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);\n}\n\nexport function json(status: number, body: unknown, headers: Record<string, string> = {}) {\n return new Response(JSON.stringify(body), {\n status,\n headers: {\n 'content-type': 'application/json; charset=utf-8',\n 'cache-control': 'no-store',\n ...headers,\n },\n });\n}\n","import { CHALLENGE_PATH, answerChallenge } from '@tryghost/app-contracts/identity';\n\nimport { parseOrigin } from '../shared/parse.ts';\nimport { json, readText } from './body.ts';\n\nexport { CHALLENGE_PATH };\n\n/**\n * A JWK, with the members RFC 7517 and RFC 7518 name. It's the package's own, as the DOM's\n * `JsonWebKey` doesn't exist in a backend that types against Node without the DOM library, and\n * a type alias rather than an interface, so a DOM `JsonWebKey` or a jose `JWK` passes for it.\n */\nexport type BackendJwk = {\n alg?: string;\n crv?: string;\n d?: string;\n dp?: string;\n dq?: string;\n e?: string;\n ext?: boolean;\n k?: string;\n key_ops?: string[];\n kid?: string;\n kty?: string;\n n?: string;\n oth?: { d?: string; r?: string; t?: string }[];\n p?: string;\n q?: string;\n qi?: string;\n use?: string;\n x?: string;\n y?: string;\n};\n\n/**\n * The backend key's private half: a JWK object, or its JSON as it sits in a secret or an\n * environment variable, such as `GHOST_APP_BACKEND_KEY`.\n */\nexport type BackendKey = BackendJwk | string;\n\nexport interface HandleChallengeOptions {\n backendKey: BackendKey;\n /**\n * The app's public origin, such as `https://app.example.com`, for a server that doesn't see\n * the scheme and host Ghost reaches it at, as Node behind a proxy that terminates TLS sees\n * `http://`. Ghost challenges the public origin, so without it every challenge is refused.\n * Take it from the app's own configuration, never from a request's headers, which the sender\n * sets. Workers, and other platforms that report the public URL, don't need it.\n */\n origin?: string;\n}\n\n// Ghost's challenge is about 150 bytes. Anything much larger isn't one.\nconst CHALLENGE_MAX_BYTES = 4 * 1024;\n\nconst INVALID_KEY =\n 'backendKey must be a private Ed25519 key as a JWK, with kty \"OKP\", crv \"Ed25519\", x and d';\n\n// The last key imported, so a backend that answers with one key imports it once.\nlet imported: { text: string; key: Promise<CryptoKey> } | undefined;\n\nfunction importBackendKey(backendKey: BackendKey): Promise<CryptoKey> {\n const text = typeof backendKey === 'string' ? backendKey : JSON.stringify(backendKey);\n if (imported?.text !== text) {\n const key = importPrivateKey(text);\n imported = { text, key };\n // A key that failed to import is tried again next time, so a fixed secret takes effect.\n key.catch(() => {\n if (imported?.key === key) {\n imported = undefined;\n }\n });\n }\n return imported.key;\n}\n\nasync function importPrivateKey(text: string): Promise<CryptoKey> {\n let jwk: unknown;\n try {\n jwk = JSON.parse(text);\n } catch {\n // Never says what the text was: it's a secret.\n throw new TypeError(`${INVALID_KEY}; it isn't JSON`);\n }\n const { kty, crv, x, d } = (typeof jwk === 'object' && jwk !== null ? jwk : {}) as BackendJwk;\n if (kty !== 'OKP' || crv !== 'Ed25519' || typeof x !== 'string' || typeof d !== 'string') {\n throw new TypeError(INVALID_KEY);\n }\n try {\n return await crypto.subtle.importKey('jwk', { kty, crv, x, d }, { name: 'Ed25519' }, false, [\n 'sign',\n ]);\n } catch (error) {\n throw new TypeError(INVALID_KEY, { cause: error });\n }\n}\n\n/**\n * Answers Ghost's challenge by signing it with the backend key. Route only `CHALLENGE_PATH`\n * to it, or use `withGhostApp`, which does.\n */\nexport async function handleChallenge(\n request: Request,\n { backendKey, origin }: HandleChallengeOptions,\n): Promise<Response> {\n // A bad `origin` is the app's own misconfiguration, so it throws, and the platform reports a\n // server error, rather than every challenge being refused with a 400 that looks like Ghost's\n // fault.\n const publicOrigin = origin === undefined ? undefined : parseOrigin(origin);\n if (origin !== undefined && !publicOrigin) {\n throw new TypeError(\n `Expected origin to be the app's origin, such as https://app.example.com, not ${origin}`,\n );\n }\n\n // Ghost always POSTs the challenge.\n if (request.method !== 'POST') {\n return json(405, { error: 'Expected a POST' }, { allow: 'POST' });\n }\n\n // A challenge is about 150 bytes, so stop reading at 4 KB rather than buffer whatever a\n // sender streams.\n let body: string | undefined;\n try {\n body = await readText(request, CHALLENGE_MAX_BYTES);\n } catch {\n return json(400, { error: 'Expected a challenge in UTF-8' });\n }\n if (body === undefined) {\n return json(413, { error: `Expected a challenge of at most ${CHALLENGE_MAX_BYTES} bytes` });\n }\n\n // Imported once and cached. A `backendKey` that isn't a private Ed25519 key throws a\n // `TypeError`, a server error, for the same reason as a bad `origin`.\n const key = await importBackendKey(backendKey);\n\n // The challenge names the origin Ghost sent it to, and is answered only for this app's own:\n // the one the platform reports in `request.url`, or `origin` behind a proxy. Never one taken\n // from `X-Forwarded-Host` or another header the sender sets, or anyone could have this\n // backend sign a challenge meant for another app.\n const result = await answerChallenge(body, {\n backendKey: key,\n requestUrl: publicOrigin ?? request.url,\n });\n if (!result.success) {\n return json(400, { error: result.error });\n }\n\n // `{ signature }`: Ghost verifies it against the backend key the signed manifest names.\n return json(200, result.answer);\n}\n","import { CHALLENGE_PATH, handleChallenge, type HandleChallengeOptions } from './challenge.ts';\n\n/**\n * A fetch handler: the request, then whatever else the platform passes, such as a Worker's `env`\n * and `ctx`.\n */\nexport type FetchHandler<Args extends unknown[] = []> = (\n request: Request,\n ...args: Args\n) => Response | Promise<Response>;\n\nexport interface GhostAppOptions<Args extends unknown[] = []> extends HandleChallengeOptions {\n /** The app's own handler, for every request but Ghost's challenge. */\n fetch: FetchHandler<Args>;\n}\n\n/**\n * The app's backend: answers Ghost's challenge at `CHALLENGE_PATH` with `handleChallenge`, and\n * passes every other request to `fetch`, with whatever else the platform passes.\n *\n * It returns `{ fetch }`, so a Worker can export it as it is, and Bun can serve it.\n */\nexport function withGhostApp<Args extends unknown[] = []>({\n fetch,\n ...challenge\n}: GhostAppOptions<Args>): { fetch: (request: Request, ...args: Args) => Promise<Response> } {\n return {\n async fetch(request, ...args) {\n if (new URL(request.url).pathname === CHALLENGE_PATH) {\n return handleChallenge(request, challenge);\n }\n return fetch(request, ...args);\n },\n };\n}\n","import type { SignedManifest } from '../shared/manifest.ts';\n\nexport { MANIFEST_PATH, type SignedManifest } from '../shared/manifest.ts';\n\n/**\n * A response that serves the signed manifest, for a backend that doesn't serve it as a static\n * file. Pass the file's text as it is, or the object it holds.\n *\n * Caches may keep it, but must check it's still current each time, so a new manifest reaches\n * Ghost the next time Ghost reads it.\n */\nexport function serveManifest(signed: SignedManifest | string): Response {\n return new Response(typeof signed === 'string' ? signed : JSON.stringify(signed), {\n headers: {\n 'content-type': 'application/json; charset=utf-8',\n 'cache-control': 'no-cache',\n },\n });\n}\n"],"mappings":"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"}
|
package/build/bin.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {}
|
package/build/bin.js
ADDED
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { a as signProject, c as KEYS_DIRECTORY, f as keyFile, g as checkApp, l as KEY_NAMES, m as readBackendKey, p as publicKeyOf, r as serialiseSigned, u as createKeys } from "./chunks/sign-BhNJAPta.js";
|
|
3
|
+
import { r as formatErrors } from "./chunks/manifest-DX1GTozy.js";
|
|
4
|
+
import { lstatSync, readlinkSync, realpathSync } from "node:fs";
|
|
5
|
+
import { mkdir, writeFile } from "node:fs/promises";
|
|
6
|
+
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
7
|
+
import { Command, CommanderError } from "commander";
|
|
8
|
+
//#region src/tooling/paths.ts
|
|
9
|
+
/** Whether `child` is `parent` or anything inside it. Both are absolute. */
|
|
10
|
+
function isWithin(parent, child) {
|
|
11
|
+
const path = relative(parent, child);
|
|
12
|
+
return path === "" || path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path);
|
|
13
|
+
}
|
|
14
|
+
var realpath = (path) => {
|
|
15
|
+
try {
|
|
16
|
+
return realpathSync.native(path);
|
|
17
|
+
} catch {
|
|
18
|
+
return;
|
|
19
|
+
}
|
|
20
|
+
};
|
|
21
|
+
var MAX_LINKS = 40;
|
|
22
|
+
/**
|
|
23
|
+
* Where writing to `path` really lands: through every link, as far as the path exists, and
|
|
24
|
+
* along a chain of dangling links to where its last one points, as writing follows them all. A
|
|
25
|
+
* path that doesn't exist yet lands in its directory, wherever that really is.
|
|
26
|
+
*/
|
|
27
|
+
function canonicalPath(path, links = 0) {
|
|
28
|
+
const existing = realpath(path);
|
|
29
|
+
if (existing) return existing;
|
|
30
|
+
if (links < MAX_LINKS && lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink()) return canonicalPath(resolve(dirname(path), readlinkSync(path)), links + 1);
|
|
31
|
+
const parent = dirname(path);
|
|
32
|
+
return join(parent === path ? parent : canonicalPath(parent, links), basename(path));
|
|
33
|
+
}
|
|
34
|
+
//#endregion
|
|
35
|
+
//#region src/cli.ts
|
|
36
|
+
var modeOf = (production) => production ? "production" : "development";
|
|
37
|
+
async function keys(root, mode, io) {
|
|
38
|
+
const { created, kept } = await createKeys({
|
|
39
|
+
root,
|
|
40
|
+
mode
|
|
41
|
+
});
|
|
42
|
+
for (const name of created) io.err(`Created ${keyFile(mode, name)}`);
|
|
43
|
+
for (const name of kept) io.err(`Kept ${keyFile(mode, name)}, which already exists`);
|
|
44
|
+
if (mode === "production" && created.includes("identity")) io.err("\nKeep a copy of the production identity key somewhere safe, such as a password manager. Sites that install the app keep its identity key, and an app signed with another key is another app.");
|
|
45
|
+
}
|
|
46
|
+
var MODES = ["development", "production"];
|
|
47
|
+
/** Throws if writing to `written` would overwrite the manifest it's signed from, or a key. */
|
|
48
|
+
function refuseToOverwrite(root, written, manifestFile) {
|
|
49
|
+
const lands = canonicalPath(written);
|
|
50
|
+
if (lands === canonicalPath(resolve(root, manifestFile))) throw new Error(`Refusing to write the signed manifest over ${manifestFile}, which it's signed from`);
|
|
51
|
+
const keysDirectory = join(root, KEYS_DIRECTORY);
|
|
52
|
+
const keyFiles = MODES.flatMap((mode) => KEY_NAMES.map((name) => canonicalPath(join(root, keyFile(mode, name)))));
|
|
53
|
+
if (isWithin(keysDirectory, written) || isWithin(canonicalPath(keysDirectory), lands) || keyFiles.includes(lands)) throw new Error(`Refusing to write the signed manifest into ${KEYS_DIRECTORY}/, which holds the keys`);
|
|
54
|
+
}
|
|
55
|
+
async function sign(root, { url, production, out, manifest }, io) {
|
|
56
|
+
const manifestFile = manifest ?? "ghost-app.json";
|
|
57
|
+
const written = out === void 0 ? void 0 : resolve(root, out);
|
|
58
|
+
if (written) refuseToOverwrite(root, written, manifestFile);
|
|
59
|
+
const result = await signProject({
|
|
60
|
+
root,
|
|
61
|
+
mode: modeOf(production),
|
|
62
|
+
manifestUrl: url,
|
|
63
|
+
manifestFile
|
|
64
|
+
});
|
|
65
|
+
if (!result.success) {
|
|
66
|
+
io.err(`${result.code}: ${manifestFile} can't be signed:\n${formatErrors(result.errors)}`);
|
|
67
|
+
return 1;
|
|
68
|
+
}
|
|
69
|
+
const text = serialiseSigned(result.signed);
|
|
70
|
+
if (written) {
|
|
71
|
+
await mkdir(dirname(written), { recursive: true });
|
|
72
|
+
await writeFile(written, text);
|
|
73
|
+
io.err(`Wrote ${written}, signed for ${String(result.manifest.manifest_url)}`);
|
|
74
|
+
} else io.out(text);
|
|
75
|
+
return 0;
|
|
76
|
+
}
|
|
77
|
+
async function check(url, io) {
|
|
78
|
+
const result = await checkApp(url);
|
|
79
|
+
if (!result.success) {
|
|
80
|
+
io.err(`${result.code}: ${result.message}`);
|
|
81
|
+
io.err(result.errors ? formatErrors(result.errors) : result.detail);
|
|
82
|
+
return 1;
|
|
83
|
+
}
|
|
84
|
+
const { manifest } = result;
|
|
85
|
+
io.out(`OK: ${manifest.name} (${manifest.id}) at ${result.manifestUrl} is signed with the identity key it names, and its origin answered the challenge with its backend key.`);
|
|
86
|
+
if (manifest.development) io.out("It is a development build, which Admin labels as one.");
|
|
87
|
+
return 0;
|
|
88
|
+
}
|
|
89
|
+
async function backendKey(root, { production, public: publicHalf, check: checkOnly }, io) {
|
|
90
|
+
const key = await readBackendKey({
|
|
91
|
+
root,
|
|
92
|
+
mode: modeOf(production)
|
|
93
|
+
});
|
|
94
|
+
if (!checkOnly) io.out(JSON.stringify(publicHalf ? publicKeyOf(key) : key));
|
|
95
|
+
}
|
|
96
|
+
/** Runs the CLI with its arguments (without `node` and the script), resolving with the exit code. */
|
|
97
|
+
async function run(args, io) {
|
|
98
|
+
let exitCode = 0;
|
|
99
|
+
const program = new Command("ghost-app").description("Creates an app's keys, signs its manifest, and checks it as Ghost does.").option("--dir <directory>", "the project's directory", ".").showHelpAfterError().exitOverride().configureOutput({
|
|
100
|
+
writeOut: io.out,
|
|
101
|
+
writeErr: io.err
|
|
102
|
+
});
|
|
103
|
+
const root = () => resolve(program.opts().dir);
|
|
104
|
+
program.command("keys").description("Creates the mode's identity and backend keys in .ghost-app/, keeping any that exist").option("--production", "the production keys instead of the development ones").action(async ({ production }) => {
|
|
105
|
+
await keys(root(), modeOf(production), io);
|
|
106
|
+
});
|
|
107
|
+
program.command("sign").description("Signs ghost-app.json for the address it will be served from").requiredOption("--url <manifest URL>", "the address the signed manifest will be served from").option("--production", "with the production keys instead of the development ones").option("--out <file>", "write it to a file in the project's directory instead of printing it").option("--manifest <file>", "sign another file than ghost-app.json").action(async (options) => {
|
|
108
|
+
exitCode = await sign(root(), options, io);
|
|
109
|
+
});
|
|
110
|
+
program.command("check").description("Checks an app as Ghost does before installing it").argument("<manifest URL>", "the address of its signed manifest").action(async (url) => {
|
|
111
|
+
exitCode = await check(url, io);
|
|
112
|
+
});
|
|
113
|
+
program.command("backend-key").description("Prints the mode's private backend key, to pipe into a secret store: ghost-app backend-key --production --check && ghost-app backend-key --production | wrangler secret put GHOST_APP_BACKEND_KEY").option("--production", "the production key instead of the development one").option("--public", "print only its public half, which is all CI needs to sign").option("--check", "print nothing, and exit 0 only if the key is there and usable").action(async (options) => {
|
|
114
|
+
await backendKey(root(), options, io);
|
|
115
|
+
});
|
|
116
|
+
try {
|
|
117
|
+
await program.parseAsync(args, { from: "user" });
|
|
118
|
+
return exitCode;
|
|
119
|
+
} catch (error) {
|
|
120
|
+
if (error instanceof CommanderError) return error.exitCode === 0 ? 0 : 2;
|
|
121
|
+
io.err(error instanceof Error ? error.message : String(error));
|
|
122
|
+
return 1;
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
//#endregion
|
|
126
|
+
//#region src/bin.ts
|
|
127
|
+
var line = (text) => text.endsWith("\n") ? text : `${text}\n`;
|
|
128
|
+
run(process.argv.slice(2), {
|
|
129
|
+
out: (text) => process.stdout.write(line(text)),
|
|
130
|
+
err: (text) => process.stderr.write(line(text))
|
|
131
|
+
}).then((code) => {
|
|
132
|
+
process.exitCode = code;
|
|
133
|
+
}, (error) => {
|
|
134
|
+
process.stderr.write(line(error instanceof Error ? error.message : String(error)));
|
|
135
|
+
process.exitCode = 1;
|
|
136
|
+
});
|
|
137
|
+
//#endregion
|
|
138
|
+
|
|
139
|
+
//# sourceMappingURL=bin.js.map
|
package/build/bin.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bin.js","names":[],"sources":["../src/tooling/paths.ts","../src/cli.ts","../src/bin.ts"],"sourcesContent":["import { lstatSync, readlinkSync, realpathSync } from 'node:fs';\nimport { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';\n\n/** Whether `child` is `parent` or anything inside it. Both are absolute. */\nexport function isWithin(parent: string, child: string): boolean {\n const path = relative(parent, child);\n // Only `..` as a whole segment climbs out: `..signed.json` is a file inside.\n return path === '' || (path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path));\n}\n\nconst realpath = (path: string) => {\n try {\n // The native one gives the case the path has on disk, where the filesystem ignores case.\n return realpathSync.native(path);\n } catch {\n return undefined;\n }\n};\n\n// As many links as Linux follows before it gives up with ELOOP.\nconst MAX_LINKS = 40;\n\n/**\n * Where writing to `path` really lands: through every link, as far as the path exists, and\n * along a chain of dangling links to where its last one points, as writing follows them all. A\n * path that doesn't exist yet lands in its directory, wherever that really is.\n */\nexport function canonicalPath(path: string, links = 0): string {\n const existing = realpath(path);\n if (existing) {\n return existing;\n }\n if (links < MAX_LINKS && lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink()) {\n return canonicalPath(resolve(dirname(path), readlinkSync(path)), links + 1);\n }\n const parent = dirname(path);\n return join(parent === path ? parent : canonicalPath(parent, links), basename(path));\n}\n","import { mkdir, writeFile } from 'node:fs/promises';\nimport { dirname, join, resolve } from 'node:path';\n\nimport { Command, CommanderError } from 'commander';\n\nimport { checkApp } from './tooling/check.ts';\nimport {\n KEYS_DIRECTORY,\n KEY_NAMES,\n createKeys,\n keyFile,\n publicKeyOf,\n readBackendKey,\n type Mode,\n} from './tooling/keys.ts';\nimport { canonicalPath, isWithin } from './tooling/paths.ts';\nimport { formatErrors } from './shared/manifest.ts';\nimport { MANIFEST_FILE, serialiseSigned, signProject } from './tooling/sign.ts';\n\nexport interface Io {\n out: (text: string) => void;\n err: (text: string) => void;\n}\n\nconst modeOf = (production: boolean | undefined): Mode =>\n production ? 'production' : 'development';\n\nasync function keys(root: string, mode: Mode, io: Io) {\n const { created, kept } = await createKeys({ root, mode });\n for (const name of created) {\n io.err(`Created ${keyFile(mode, name)}`);\n }\n for (const name of kept) {\n io.err(`Kept ${keyFile(mode, name)}, which already exists`);\n }\n if (mode === 'production' && created.includes('identity')) {\n io.err(\n '\\nKeep a copy of the production identity key somewhere safe, such as a password manager. ' +\n 'Sites that install the app keep its identity key, and an app signed with another key is another app.',\n );\n }\n}\n\nconst MODES: readonly Mode[] = ['development', 'production'];\n\n/** Throws if writing to `written` would overwrite the manifest it's signed from, or a key. */\nfunction refuseToOverwrite(root: string, written: string, manifestFile: string) {\n // Where the write would really land, through every link.\n const lands = canonicalPath(written);\n if (lands === canonicalPath(resolve(root, manifestFile))) {\n throw new Error(\n `Refusing to write the signed manifest over ${manifestFile}, which it's signed from`,\n );\n }\n // Refused by the path as written, by where it really lands, and by where each key really is,\n // so neither a link out of .ghost-app/ nor a key that is itself a link lets it reach a key.\n const keysDirectory = join(root, KEYS_DIRECTORY);\n const keyFiles = MODES.flatMap((mode) =>\n KEY_NAMES.map((name) => canonicalPath(join(root, keyFile(mode, name)))),\n );\n if (\n isWithin(keysDirectory, written) ||\n isWithin(canonicalPath(keysDirectory), lands) ||\n keyFiles.includes(lands)\n ) {\n throw new Error(\n `Refusing to write the signed manifest into ${KEYS_DIRECTORY}/, which holds the keys`,\n );\n }\n}\n\nasync function sign(\n root: string,\n {\n url,\n production,\n out,\n manifest,\n }: { url: string; production?: boolean; out?: string; manifest?: string },\n io: Io,\n) {\n const manifestFile = manifest ?? MANIFEST_FILE;\n // Against the project's directory, like --manifest and the keys.\n const written = out === undefined ? undefined : resolve(root, out);\n if (written) {\n refuseToOverwrite(root, written, manifestFile);\n }\n const result = await signProject({\n root,\n mode: modeOf(production),\n manifestUrl: url,\n manifestFile,\n });\n if (!result.success) {\n io.err(`${result.code}: ${manifestFile} can't be signed:\\n${formatErrors(result.errors)}`);\n return 1;\n }\n const text = serialiseSigned(result.signed);\n if (written) {\n await mkdir(dirname(written), { recursive: true });\n await writeFile(written, text);\n io.err(`Wrote ${written}, signed for ${String(result.manifest.manifest_url)}`);\n } else {\n io.out(text);\n }\n return 0;\n}\n\nasync function check(url: string, io: Io) {\n const result = await checkApp(url);\n if (!result.success) {\n io.err(`${result.code}: ${result.message}`);\n io.err(result.errors ? formatErrors(result.errors) : result.detail);\n return 1;\n }\n const { manifest } = result;\n io.out(\n `OK: ${manifest.name} (${manifest.id}) at ${result.manifestUrl} is signed with the identity key it names, and its origin answered the challenge with its backend key.`,\n );\n if (manifest.development) {\n io.out('It is a development build, which Admin labels as one.');\n }\n return 0;\n}\n\nasync function backendKey(\n root: string,\n {\n production,\n public: publicHalf,\n check: checkOnly,\n }: { production?: boolean; public?: boolean; check?: boolean },\n io: Io,\n) {\n // Reading the key checks it, and fails with what's wrong, never with the key.\n const key = await readBackendKey({ root, mode: modeOf(production) });\n if (!checkOnly) {\n io.out(JSON.stringify(publicHalf ? publicKeyOf(key) : key));\n }\n}\n\n/** Runs the CLI with its arguments (without `node` and the script), resolving with the exit code. */\nexport async function run(args: string[], io: Io): Promise<number> {\n let exitCode = 0;\n const program = new Command('ghost-app')\n .description(\"Creates an app's keys, signs its manifest, and checks it as Ghost does.\")\n .option('--dir <directory>', \"the project's directory\", '.')\n .showHelpAfterError()\n // Thrown rather than exiting, so `run` resolves with the code, and prints through `io`.\n .exitOverride()\n .configureOutput({ writeOut: io.out, writeErr: io.err });\n const root = () => resolve(program.opts<{ dir: string }>().dir);\n\n program\n .command('keys')\n .description(\n \"Creates the mode's identity and backend keys in .ghost-app/, keeping any that exist\",\n )\n .option('--production', 'the production keys instead of the development ones')\n .action(async ({ production }: { production?: boolean }) => {\n await keys(root(), modeOf(production), io);\n });\n\n program\n .command('sign')\n .description('Signs ghost-app.json for the address it will be served from')\n .requiredOption('--url <manifest URL>', 'the address the signed manifest will be served from')\n .option('--production', 'with the production keys instead of the development ones')\n .option('--out <file>', \"write it to a file in the project's directory instead of printing it\")\n .option('--manifest <file>', 'sign another file than ghost-app.json')\n .action(async (options: Parameters<typeof sign>[1]) => {\n exitCode = await sign(root(), options, io);\n });\n\n program\n .command('check')\n .description('Checks an app as Ghost does before installing it')\n .argument('<manifest URL>', 'the address of its signed manifest')\n .action(async (url: string) => {\n exitCode = await check(url, io);\n });\n\n program\n .command('backend-key')\n .description(\n \"Prints the mode's private backend key, to pipe into a secret store: ghost-app backend-key --production --check && ghost-app backend-key --production | wrangler secret put GHOST_APP_BACKEND_KEY\",\n )\n .option('--production', 'the production key instead of the development one')\n .option('--public', 'print only its public half, which is all CI needs to sign')\n .option('--check', 'print nothing, and exit 0 only if the key is there and usable')\n .action(async (options: Parameters<typeof backendKey>[1]) => {\n await backendKey(root(), options, io);\n });\n\n try {\n await program.parseAsync(args, { from: 'user' });\n return exitCode;\n } catch (error) {\n // Commander has already printed help, or the mistake and the help: 0 for asking for help,\n // and 2 for a mistake in how the CLI was called.\n if (error instanceof CommanderError) {\n return error.exitCode === 0 ? 0 : 2;\n }\n io.err(error instanceof Error ? error.message : String(error));\n return 1;\n }\n}\n","#!/usr/bin/env node\nimport { run } from './cli.ts';\n\nconst line = (text: string) => (text.endsWith('\\n') ? text : `${text}\\n`);\n\nrun(process.argv.slice(2), {\n out: (text) => process.stdout.write(line(text)),\n err: (text) => process.stderr.write(line(text)),\n}).then(\n (code) => {\n process.exitCode = code;\n },\n // run reports its own failures, so this is a bug: say what, without a stack trace.\n (error: unknown) => {\n process.stderr.write(line(error instanceof Error ? error.message : String(error)));\n process.exitCode = 1;\n },\n);\n"],"mappings":"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"}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
//#region src/shared/manifest.d.ts
|
|
2
|
+
/** Where an app serves its signed manifest by convention, and where the SDK's tooling signs it for. */
|
|
3
|
+
declare const MANIFEST_PATH = "/ghost-app.json";
|
|
4
|
+
/** A signed manifest: flattened JWS JSON, as `ghost-app sign` or the Vite plugin writes it. */
|
|
5
|
+
interface SignedManifest {
|
|
6
|
+
protected: string;
|
|
7
|
+
payload: string;
|
|
8
|
+
signature: string;
|
|
9
|
+
}
|
|
10
|
+
/** One problem with a manifest. */
|
|
11
|
+
interface ManifestError {
|
|
12
|
+
/** Where in the manifest the problem is, such as `surfaces[0].url`. Empty for the whole. */
|
|
13
|
+
path: string;
|
|
14
|
+
message: string;
|
|
15
|
+
}
|
|
16
|
+
/** A manifest's problems, one per line, as `path: message`. */
|
|
17
|
+
declare function formatErrors(errors: readonly ManifestError[], separator?: string): string;
|
|
18
|
+
//#endregion
|
|
19
|
+
export { formatErrors as i, ManifestError as n, SignedManifest as r, MANIFEST_PATH as t };
|