@pwfabric/cli 0.0.0-stage → 1.0.0-rc.0

package/dist/dev/csp.js

@@ -0,0 +1,260 @@
+/**
+ * The app's Content Security Policy, derived from what the app declares.
+ *
+ * A pwapp is static files; what it may load and reach is known at build time
+ * from its own declarations, so `pwf build` writes a policy that allows that
+ * and nothing else (pwapp-format §2.1):
+ *
+ *   default-src  'none'
+ *   script-src   'self' blob: 'sha256-<import map>'
+ *                Blocks and compiled engines are verified and then imported
+ *                from `blob:` URLs. The import map is the shell's only inline
+ *                script (an import map cannot be an external file), so its
+ *                hash is listed; the renderer seeding and the boot call are
+ *                files (`assets/seed.js`, `assets/boot.js`).
+ *   style-src    'self' 'unsafe-inline' [+ the webfont stylesheet origin]
+ *                The renderer draws `<style>` elements at run time (the
+ *                surface base, visibility, state, responsive and dark-theme
+ *                rules, computed per page), and blocks set `style`
+ *                attributes. Neither can be hashed ahead of time.
+ *   img-src      'self' data: blob: [+ media origins]
+ *   media-src    'self' data: blob: [+ media origins]
+ *   frame-src    [media origins] — only when there are any
+ *   font-src     'self' [+ the webfont file origin]
+ *   connect-src  'self' [+ every origin the app's data and sign-in reach]
+ *   base-uri     'self'  — a host that serves the app under a sub-path
+ *                injects `<base href>` (pwapp-format §2); 'none' would make
+ *                the browser ignore it and break path routing.
+ *   object-src   'none'
+ *   frame-ancestors 'none'  — header only: browsers ignore it in a `<meta>`.
+ *
+ * Origins come from: absolute `rest` endpoints in the receipts; declared
+ * engines' `host` templates filled from `connections.json` config;
+ * the envelope `auth.json` addresses and an external issuer; `publish.json`
+ * media and absolute media URLs in receipt props. A template that cannot be
+ * resolved at build time, and a compiled engine (whose code may reach any
+ * origin), is listed in `unresolved` instead of being guessed.
+ *
+ * @module @pwfabric/cli/dev/csp
+ */
+import { createHash } from 'node:crypto';
+import { isRecord } from './sources.js';
+/** Directives a `<meta http-equiv="Content-Security-Policy">` cannot carry (CSP3 §3.3). */
+const HEADER_ONLY = new Set(['frame-ancestors', 'report-uri', 'report-to', 'sandbox']);
+/** The CSP source for an inline script: `'sha256-<base64>'` of its exact text. */
+export function scriptHash(text) {
+    return `'sha256-${createHash('sha256').update(text, 'utf8').digest('base64')}'`;
+}
+const LOOPBACK = /^(?:localhost|127\.0\.0\.1|\[::1\]|[^/:]+\.localhost)(?::\d+)?$/i;
+/**
+ * The origin of an absolute http(s) URL, or null. Expressions (`{{…}}`) or
+ * templates (`{…}`) in the scheme or host make it unresolvable (`undefined`).
+ */
+export function originOf(value) {
+    const m = /^(https?):\/\/([^/?#]*)/i.exec(value.trim());
+    if (!m)
+        return null;
+    const host = m[2];
+    if (!host || /[{}]/.test(host))
+        return undefined;
+    try {
+        return new URL(`${m[1].toLowerCase()}://${host}`).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The origin a declared engine's `host` reaches (connector-manifest §3.1):
+ * `{name}` filled from the connection's string config, the scheme dropped and
+ * `https://` prepended, except an explicit `http://` on a loopback host.
+ * `undefined` when a placeholder stays unfilled.
+ */
+export function engineHostOrigin(host, config) {
+    const filled = host.replace(/\{([A-Za-z0-9_.-]+)\}/g, (whole, name) => {
+        const v = config?.[name];
+        return typeof v === 'string' ? v : whole;
+    });
+    if (/[{}]/.test(filled))
+        return undefined;
+    const explicitHttp = /^http:\/\//i.test(filled.trim());
+    const bare = filled.trim().replace(/^[a-z][a-z0-9+.-]*:\/\//i, '');
+    const hostPart = bare.split(/[/?#]/)[0] ?? '';
+    if (!hostPart)
+        return undefined;
+    const scheme = explicitHttp && LOOPBACK.test(hostPart) ? 'http' : 'https';
+    try {
+        return new URL(`${scheme}://${hostPart}`).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A prop that names where a link goes (navigation is not governed by CSP). */
+const LINK_PROP = /^(?:href|to|link|url|.*Href|.*Link)$/;
+/** Every absolute URL a receipt's block props carry, except links. */
+function mediaUrlsOf(blocks, out) {
+    if (!Array.isArray(blocks))
+        return;
+    for (const block of blocks) {
+        if (!isRecord(block))
+            continue;
+        const props = block['props'];
+        if (isRecord(props))
+            collectUrls(props, out);
+        mediaUrlsOf(block['children'], out);
+    }
+}
+function collectUrls(value, out) {
+    const entries = Array.isArray(value) ? value.map((v, i) => [String(i), v]) : Object.entries(value);
+    for (const [key, v] of entries) {
+        if (typeof v === 'string') {
+            if (!LINK_PROP.test(key) && /^https?:\/\//i.test(v.trim()))
+                out.push(v.trim());
+        }
+        else if (Array.isArray(v) || isRecord(v)) {
+            collectUrls(v, out);
+        }
+    }
+}
+/** `rest` data sources of a receipt's persistence capability. */
+function restEndpointsOf(receipt) {
+    if (!isRecord(receipt) || !Array.isArray(receipt['capabilities']))
+        return [];
+    const out = [];
+    for (const cap of receipt['capabilities']) {
+        if (!isRecord(cap) || !isRecord(cap['config']))
+            continue;
+        const sources = cap['config']['dataSources'];
+        if (!Array.isArray(sources))
+            continue;
+        for (const s of sources) {
+            if (isRecord(s) && s['kind'] === 'rest' && typeof s['endpoint'] === 'string')
+                out.push(s['endpoint']);
+        }
+    }
+    return out;
+}
+const AUTH_ADDRESS_KEYS = ['loginUrl', 'registerUrl', 'logoutUrl', 'sessionUrl', 'tokenUrl', 'issuer', 'startUrl', 'gatewaySessionUrl', 'gatewayLogoutUrl'];
+/** Writes the directives as a policy string. */
+export function serializeCsp(directives, options = {}) {
+    return Object.entries(directives)
+        .filter(([name, values]) => values.length > 0 && !(options.meta && HEADER_ONLY.has(name)))
+        .map(([name, values]) => `${name} ${values.join(' ')}`)
+        .join('; ');
+}
+/** Derives the app's policy from what it declares. */
+export function deriveCsp(input) {
+    const unresolved = [];
+    const connect = new Set();
+    const media = new Set();
+    const style = new Set();
+    const font = new Set();
+    const addConnect = (value, source) => {
+        const o = originOf(value);
+        if (o === undefined)
+            unresolved.push({ source, value, reason: 'the address is a template or expression; its origin is known only at run time' });
+        else if (o)
+            connect.add(o);
+    };
+    // Data: absolute `rest` endpoints in the receipts. Relative ones are 'self'.
+    for (const [key, receipt] of input.receipts) {
+        for (const endpoint of restEndpointsOf(receipt))
+            addConnect(endpoint, `page:${key}`);
+        const urls = [];
+        if (isRecord(receipt))
+            mediaUrlsOf(receipt['blocks'], urls);
+        for (const url of urls) {
+            const o = originOf(url);
+            if (o)
+                media.add(o);
+            else if (o === undefined)
+                unresolved.push({ source: `page:${key}`, value: url, reason: 'a media address with an expression in its origin' });
+        }
+    }
+    // Connections: declared engines resolve their host; compiled ones cannot be read.
+    const configOf = new Map();
+    for (const c of input.connections?.connections ?? []) {
+        if (typeof c['name'] === 'string')
+            configOf.set(c['name'], isRecord(c['config']) ? c['config'] : {});
+    }
+    for (const e of input.engines) {
+        const host = isRecord(e.engine) && typeof e.engine['host'] === 'string' ? e.engine['host'] : undefined;
+        if (host !== undefined) {
+            const o = engineHostOrigin(host, configOf.get(e.connection));
+            if (o)
+                connect.add(o);
+            else
+                unresolved.push({ source: `connection:${e.connection}`, value: host, reason: 'the engine host names config the connection does not provide' });
+        }
+        else if (e.moduleUrl) {
+            unresolved.push({
+                source: `engine:${e.atomId}`,
+                value: e.moduleUrl,
+                reason: `compiled engine for connection "${e.connection}"; the origins its code reaches are not declared`,
+            });
+        }
+    }
+    // Sign-in: the envelope's addresses, and an external issuer's.
+    if (isRecord(input.envelopeAuth)) {
+        for (const k of AUTH_ADDRESS_KEYS) {
+            const v = input.envelopeAuth[k];
+            if (typeof v === 'string')
+                addConnect(v, 'auth');
+        }
+    }
+    const issuer = isRecord(input.authDefinition) && isRecord(input.authDefinition['issuer']) ? input.authDefinition['issuer'] : undefined;
+    if (issuer) {
+        for (const k of ['issuer', 'tokenUrl']) {
+            const v = issuer[k];
+            if (typeof v === 'string')
+                addConnect(v, 'auth');
+        }
+        if (typeof issuer['tokenUrl'] !== 'string' && typeof issuer['issuer'] === 'string') {
+            unresolved.push({
+                source: 'auth',
+                value: issuer['issuer'],
+                reason: "the token endpoint is discovered at run time; the policy allows the issuer's own origin only",
+            });
+        }
+    }
+    // Media the app declares.
+    for (const m of input.media) {
+        const o = originOf(m.url);
+        if (o)
+            media.add(o);
+    }
+    // Webfonts: the stylesheet and the files it points at.
+    if (input.webfontHref) {
+        const o = originOf(input.webfontHref);
+        if (o)
+            style.add(o);
+        if (o === 'https://fonts.googleapis.com')
+            font.add('https://fonts.gstatic.com');
+    }
+    const sorted = (s) => [...s].sort();
+    const directives = {
+        'default-src': ["'none'"],
+        'script-src': ["'self'", 'blob:', scriptHash(input.importMapText)],
+        'style-src': ["'self'", "'unsafe-inline'", ...sorted(style)],
+        'img-src': ["'self'", 'data:', 'blob:', ...sorted(media)],
+        'media-src': ["'self'", 'data:', 'blob:', ...sorted(media)],
+        ...(media.size > 0 ? { 'frame-src': sorted(media) } : {}),
+        'font-src': ["'self'", ...sorted(font)],
+        'connect-src': ["'self'", ...sorted(connect)],
+        'base-uri': ["'self'"],
+        'object-src': ["'none'"],
+        'frame-ancestors': ["'none'"],
+    };
+    return {
+        directives,
+        header: serializeCsp(directives),
+        meta: serializeCsp(directives, { meta: true }),
+        unresolved,
+    };
+}
+/** The static-host `_headers` file (`/*` and the policy). */
+export function headersFile(policy) {
+    return `/*\n  Content-Security-Policy: ${policy}\n`;
+}
+//# sourceMappingURL=csp.js.map

package/dist/dev/csp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csp.js","sourceRoot":"","sources":["../../src/dev/csp.ts"],"names":[],"mappings":"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"}

package/dist/dev/diagnostics.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What an assembly says about the folder it read: one shape for compiler
+ * output, validation findings and the assembler's own checks, so the terminal
+ * and the overlay page print the same list.
+ */
+export type AssembleSeverity = 'error' | 'warning' | 'info';
+export interface AssembleDiagnostic {
+    readonly severity: AssembleSeverity;
+    /** Machine-readable reason, e.g. `PACK_NOT_CACHED` or a compiler code. */
+    readonly code: string;
+    readonly message: string;
+    /** The file the finding is about, relative to the app folder when it can be. */
+    readonly path?: string;
+    readonly line?: number;
+    readonly column?: number;
+}
+/** `error  app/surfaces/home.receipt.json:3:7  UNKNOWN_BLOCK_TYPE  …` */
+export declare function formatDiagnostic(d: AssembleDiagnostic): string;
+export declare function hasErrors(diagnostics: readonly AssembleDiagnostic[]): boolean;
+/** Errors first, then warnings, then info; stable within a severity. */
+export declare function sortDiagnostics(diagnostics: readonly AssembleDiagnostic[]): AssembleDiagnostic[];
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/dev/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/dev/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;AAE3D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,gFAAgF;IAChF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAG9D;AAED,wBAAgB,SAAS,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,GAAG,OAAO,CAE7E;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,GAAG,kBAAkB,EAAE,CAMhG"}

package/dist/dev/diagnostics.js

@@ -0,0 +1,22 @@
+/**
+ * What an assembly says about the folder it read: one shape for compiler
+ * output, validation findings and the assembler's own checks, so the terminal
+ * and the overlay page print the same list.
+ */
+/** `error  app/surfaces/home.receipt.json:3:7  UNKNOWN_BLOCK_TYPE  …` */
+export function formatDiagnostic(d) {
+    const where = d.path ? `${d.path}${d.line !== undefined ? `:${d.line}${d.column !== undefined ? `:${d.column}` : ''}` : ''}  ` : '';
+    return `${d.severity.padEnd(7)} ${where}${d.code}  ${d.message}`;
+}
+export function hasErrors(diagnostics) {
+    return diagnostics.some((d) => d.severity === 'error');
+}
+/** Errors first, then warnings, then info; stable within a severity. */
+export function sortDiagnostics(diagnostics) {
+    const rank = { error: 0, warning: 1, info: 2 };
+    return diagnostics
+        .map((d, i) => [d, i])
+        .sort((a, b) => rank[a[0].severity] - rank[b[0].severity] || a[1] - b[1])
+        .map(([d]) => d);
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/dev/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/dev/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,yEAAyE;AACzE,MAAM,UAAU,gBAAgB,CAAC,CAAqB;IACpD,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IACnI,OAAO,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAA;AAClE,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,WAA0C;IAClE,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAA;AACxD,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,eAAe,CAAC,WAA0C;IACxE,MAAM,IAAI,GAAqC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA;IAChF,OAAO,WAAW;SACf,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAU,CAAC;SAC9B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;SACxE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAA;AACpB,CAAC"}

package/dist/dev/envelope.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The envelope documents a runner reads (`pwpack/project.json`,
+ * `navigation.json`, `connections.json`, the two module manifests), built
+ * from the app folder's declaration.
+ */
+import type { AssembleDiagnostic } from './diagnostics.js';
+/** One page of the app: its key, its receipt and what the receipt says. */
+export interface Page {
+    readonly key: string;
+    /** Path of the receipt in the app folder. */
+    readonly path: string;
+    readonly bytes: Uint8Array;
+    readonly receipt: Record<string, unknown>;
+}
+/** The block types a receipt places, walking `blocks` and every `children`. */
+export declare function blockTypesOf(receipt: unknown): string[];
+/** The page's display name: the receipt's title, else the key. */
+export declare function pageLabel(page: Page): string;
+/** Navigation derived from the route table when the app declares none. */
+export declare function deriveNavigation(pages: readonly Page[], entry: string): {
+    navbar: {
+        links: {
+            label: string;
+            href: string;
+        }[];
+    };
+};
+/** What the app declares about who may enter (`app/definitions/auth.json`), as `project.json` carries it. */
+export declare function identityOf(auth: unknown): {
+    required: boolean;
+    topology: 'app' | 'external';
+    methods?: string[];
+} | undefined;
+export interface ProjectJsonInput {
+    readonly id: string;
+    readonly title: string;
+    readonly entry: string;
+    readonly pages: readonly Page[];
+    readonly auth?: unknown;
+}
+/** `pwpack/project.json`. */
+export declare function buildProjectJson(input: ProjectJsonInput): Record<string, unknown>;
+/** Config keys that smell of a credential. Such a key never reaches a published app. */
+export declare const CREDENTIAL_KEY_RE: RegExp;
+/**
+ * `pwpack/connections.json`: the declaration with every credential-like
+ * config key removed (each removal is reported). A bare string entry is read
+ * as `{ name }`.
+ */
+export declare function buildConnections(doc: unknown, diagnostics: AssembleDiagnostic[], path?: string): {
+    connections: Record<string, unknown>[];
+} | undefined;
+/** One entry of `blocks/manifest.json`. */
+export interface BlockManifestEntry {
+    readonly blockType: string;
+    readonly moduleUrl: string;
+    readonly integrity: string;
+    readonly publisher: string;
+    readonly publisherVerified: boolean;
+    readonly definition: {
+        readonly name: string;
+    };
+}
+/** One entry of `engines/manifest.json`. */
+export interface EngineManifestEntry {
+    readonly connection: string;
+    readonly atomId: string;
+    readonly kind: 'connector' | 'provider';
+    readonly moduleUrl?: string;
+    readonly integrity?: string;
+    readonly engine?: unknown;
+}
+/** A file name for a module: `<name>.<first 8 hex of its hash>.mjs`, with anything unsafe replaced. */
+export declare function moduleFileName(name: string, hexHash: string): string;
+/** The publisher an atom is attributed to: the pack id's publisher segment, or the id itself. */
+export declare function publisherOf(packId: string): string;
+/**
+ * Whether a local host may write `name` into the envelope: a relative path of
+ * `/`-separated segments ending in `.json` (`auth.json`,
+ * `surfaces/home.receipt.json`), each segment starting with a letter, digit,
+ * `_` or `-` — so no `.`/`..` segment, no hidden file, no absolute path.
+ */
+export declare function isEnvelopeFileName(name: string): boolean;
+/**
+ * Merges what a local host adds to the envelope. Each key is a file name
+ * relative to `pwpack/` (`auth.json`, `surfaces/<key>.receipt.json`) and each
+ * value the document; a value for `project.json` is merged into it member by
+ * member. Called after the static envelope is laid out, so what the host
+ * offers WINS: its receipts (entity sources rewritten to its record
+ * endpoints) replace the folder's copies.
+ */
+export declare function mergeEnvelopeEntries(files: Map<string, Uint8Array>, entries: Readonly<Record<string, unknown>> | undefined, diagnostics: AssembleDiagnostic[]): void;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/dev/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/dev/envelope.ts"],"names":[],"mappings":"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"}

package/dist/dev/envelope.js

@@ -0,0 +1,154 @@
+import { isRecord } from './sources.js';
+/** The block types a receipt places, walking `blocks` and every `children`. */
+export function blockTypesOf(receipt) {
+    const types = new Set();
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            node.forEach(walk);
+            return;
+        }
+        if (!isRecord(node))
+            return;
+        if (typeof node['type'] === 'string' && node['type'])
+            types.add(node['type']);
+        if (Array.isArray(node['children']))
+            node['children'].forEach(walk);
+    };
+    if (isRecord(receipt))
+        walk(receipt['blocks']);
+    return [...types];
+}
+/** The page's display name: the receipt's title, else the key. */
+export function pageLabel(page) {
+    const title = page.receipt['title'];
+    return typeof title === 'string' && title.trim() ? title.trim() : page.key;
+}
+/** Navigation derived from the route table when the app declares none. */
+export function deriveNavigation(pages, entry) {
+    return {
+        navbar: { links: pages.map((p) => ({ label: pageLabel(p), href: p.key === entry ? '/' : `/${p.key}` })) },
+    };
+}
+/** What the app declares about who may enter (`app/definitions/auth.json`), as `project.json` carries it. */
+export function identityOf(auth) {
+    if (!isRecord(auth))
+        return undefined;
+    const topology = auth['topology'] === 'external' ? 'external' : 'app';
+    const methods = Array.isArray(auth['methods']) ? auth['methods'].filter((m) => typeof m === 'string') : [];
+    return {
+        required: auth['required'] === true,
+        topology,
+        ...(topology === 'app' ? { methods } : {}),
+    };
+}
+/** `pwpack/project.json`. */
+export function buildProjectJson(input) {
+    const surfaceReceiptFiles = {};
+    for (const p of input.pages)
+        surfaceReceiptFiles[p.key] = `surfaces/${p.key}.receipt.json`;
+    const identity = identityOf(input.auth);
+    return {
+        schemaVersion: '1.0.0',
+        id: input.id,
+        title: input.title,
+        entrySurfaceId: input.entry,
+        surfaceOrder: input.pages.map((p) => p.key),
+        surfaceReceiptFiles,
+        ...(identity ? { identity } : {}),
+    };
+}
+/** Config keys that smell of a credential. Such a key never reaches a published app. */
+export const CREDENTIAL_KEY_RE = /(auth|header|credential|secret|token|password|passwd|apikey|api_key|clientsecret|client_secret|bearer|cookie|signature)/i;
+function stripCredentials(value, path, dropped) {
+    if (Array.isArray(value))
+        return value.map((v, i) => stripCredentials(v, `${path}[${i}]`, dropped));
+    if (!isRecord(value))
+        return value;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (CREDENTIAL_KEY_RE.test(k)) {
+            dropped.push(`${path}.${k}`);
+            continue;
+        }
+        out[k] = stripCredentials(v, `${path}.${k}`, dropped);
+    }
+    return out;
+}
+/**
+ * `pwpack/connections.json`: the declaration with every credential-like
+ * config key removed (each removal is reported). A bare string entry is read
+ * as `{ name }`.
+ */
+export function buildConnections(doc, diagnostics, path = 'app/definitions/connections.json') {
+    if (!isRecord(doc))
+        return undefined;
+    const list = Array.isArray(doc['connections']) ? doc['connections'] : [];
+    const connections = [];
+    for (const raw of list) {
+        const entry = typeof raw === 'string' ? { name: raw } : isRecord(raw) ? raw : null;
+        if (!entry || typeof entry['name'] !== 'string') {
+            diagnostics.push({ severity: 'warning', code: 'CONNECTION_INVALID', message: 'a connection without a name is skipped', path });
+            continue;
+        }
+        const dropped = [];
+        const out = { ...entry };
+        if (entry['config'] !== undefined)
+            out['config'] = stripCredentials(entry['config'], 'config', dropped);
+        for (const d of dropped) {
+            diagnostics.push({
+                severity: 'warning',
+                code: 'CREDENTIAL_DROPPED',
+                message: `connection "${entry['name']}": ${d} looks like a credential and is not published`,
+                path,
+            });
+        }
+        connections.push(out);
+    }
+    return { connections };
+}
+/** A file name for a module: `<name>.<first 8 hex of its hash>.mjs`, with anything unsafe replaced. */
+export function moduleFileName(name, hexHash) {
+    const safe = name.replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^\.+/, '_') || 'module';
+    return `${safe}.${hexHash.slice(0, 8)}.mjs`;
+}
+/** The publisher an atom is attributed to: the pack id's publisher segment, or the id itself. */
+export function publisherOf(packId) {
+    const m = /^@pwpack\/([^/]+)\//.exec(packId);
+    return m?.[1] ?? packId;
+}
+/**
+ * Whether a local host may write `name` into the envelope: a relative path of
+ * `/`-separated segments ending in `.json` (`auth.json`,
+ * `surfaces/home.receipt.json`), each segment starting with a letter, digit,
+ * `_` or `-` — so no `.`/`..` segment, no hidden file, no absolute path.
+ */
+export function isEnvelopeFileName(name) {
+    return /^(?:[A-Za-z0-9_-][A-Za-z0-9_.-]*\/)*[A-Za-z0-9_-][A-Za-z0-9_.-]*\.json$/.test(name);
+}
+/**
+ * Merges what a local host adds to the envelope. Each key is a file name
+ * relative to `pwpack/` (`auth.json`, `surfaces/<key>.receipt.json`) and each
+ * value the document; a value for `project.json` is merged into it member by
+ * member. Called after the static envelope is laid out, so what the host
+ * offers WINS: its receipts (entity sources rewritten to its record
+ * endpoints) replace the folder's copies.
+ */
+export function mergeEnvelopeEntries(files, entries, diagnostics) {
+    if (!entries)
+        return;
+    const enc = new TextEncoder();
+    for (const [name, value] of Object.entries(entries)) {
+        if (!isEnvelopeFileName(name)) {
+            diagnostics.push({ severity: 'warning', code: 'HOST_ENTRY_IGNORED', message: `the local host offered "${name}", which is not an envelope file name` });
+            continue;
+        }
+        const path = `pwpack/${name}`;
+        if (name === 'project.json' && isRecord(value)) {
+            const current = JSON.parse(new TextDecoder().decode(files.get(path)));
+            files.set(path, enc.encode(JSON.stringify({ ...current, ...value })));
+            continue;
+        }
+        files.set(path, enc.encode(JSON.stringify(value)));
+    }
+}
+//# sourceMappingURL=envelope.js.map

package/dist/dev/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/dev/envelope.ts"],"names":[],"mappings":"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"}

package/dist/dev/media.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Media: the app's declared images and files, copied into the pwapp.
+ *
+ * pwpack-format §1.3: `app/media/<key>.json` declares one image or file
+ * (`{ purpose, kind, origin, slots, status, url?, decorative?, file? }`) and
+ * carries no bytes; the bytes are `media/<file>`, each recorded in
+ * `media/provenance.json`. The pack library's `mediaDeclarations` reads
+ * that layout (its findings reach the diagnostics through `validatePack`).
+ * pwapp-format §1 puts the bytes the app serves at `pwpack/media/<file>`,
+ * and §4 records each declaration's resolved address in `publish.json`
+ * `media[]`.
+ *
+ * For each declaration the bytes are looked up, in order:
+ *
+ *   1. the declaration's `file` (a pack path, `media/<name>`);
+ *   2. `media/<path>` — a `url` that is itself a `media/…` path;
+ *   3. `media/<key>.<ext>` — the one media file named after the key.
+ *
+ * Found bytes are served at `pwpack/media/…` and the declaration resolves to
+ * that address. A declaration without bytes but with an absolute `url` keeps
+ * the url. Every other one is reported (info) and left alone.
+ *
+ * Slots: a declared slot (`{ surfaceKey, blockId, prop }`) whose prop is
+ * empty in the served receipt gets the resolved address. A value already in
+ * the prop is never replaced (plan.md §2 rule 1). The app's own files are
+ * never rewritten; only the served copy of the receipt is.
+ */
+import { type PackFolder } from '@pwfabric/pack';
+import type { AssembleDiagnostic } from './diagnostics.js';
+/** One slot a resolved address is written into. */
+export interface MediaSlot {
+    readonly blockId: string;
+    readonly prop: string;
+    readonly url: string;
+}
+export interface CollectedMedia {
+    /** Files to serve, relative to `pwpack/` (`media/hero.webp`). */
+    readonly files: Map<string, Uint8Array>;
+    /** `publish.json` `media[]`, in key order. */
+    readonly records: {
+        key: string;
+        url: string;
+    }[];
+    /** Slots to fill, by page key. */
+    readonly slots: Map<string, MediaSlot[]>;
+}
+/** Reads the app's media declarations and bytes. */
+export declare function collectMedia(folder: PackFolder, diagnostics: AssembleDiagnostic[]): CollectedMedia;
+/**
+ * The served receipt with its empty media slots filled, or `undefined` when
+ * nothing changed (the bytes are then served exactly as written).
+ */
+export declare function fillMediaSlots(receiptBytes: Uint8Array, slots: readonly MediaSlot[] | undefined): Uint8Array | undefined;
+//# sourceMappingURL=media.d.ts.map