@cadence-app/compiler 0.4.0 → 0.5.0

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.
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Le lien que porte le QR : l'adresse du serveur, telle que le conteneur la
3
+ * composera ensuite.
4
+ *
5
+ * L'adresse n'est pas encodée. `:` et `/` sont permis dans une query, et un
6
+ * `%3A` de plus par caractère ferait grossir le QR pour rien — une adresse de
7
+ * serveur de développement ne porte ni `&` ni `=`.
8
+ *
9
+ * La barre oblique avant la query n'est pas décorative : un lien au chemin vide
10
+ * se lit différemment d'un cadre d'hôte à l'autre, et plusieurs n'en tirent
11
+ * alors aucune route.
12
+ */
13
+ export declare function pairingDeepLink(baseUrl: string): string;
14
+ /**
15
+ * Le lien que porte le QR d'un canal de développement : l'adresse que
16
+ * l'appareil interrogera (ADR-038).
17
+ *
18
+ * Même forme et mêmes raisons que celle d'un serveur local, au paramètre près.
19
+ * Le code court reste la voie sans appareil photo ; ce lien est celle qui
20
+ * épargne de le recopier.
21
+ */
22
+ export declare function channelDeepLink(pollUrl: string): string;
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Le schéma que les hôtes de démonstration enregistrent pour recevoir une
3
+ * adresse de serveur de développement.
4
+ *
5
+ * Un seul schéma pour les deux hôtes : installer les deux sur le même
6
+ * téléphone fait demander lequel ouvrir, ce qui est la bonne réponse. Une
7
+ * super-app réelle choisit le sien.
8
+ */
9
+ const PAIRING_SCHEME = 'cadence-dev';
10
+ const PAIRING_ACTION = 'pair';
11
+ const PAIRING_URL_PARAMETER = 'url';
12
+ /**
13
+ * Un canal se nomme par un paramètre à lui, et non par la même adresse.
14
+ *
15
+ * Les deux portent une adresse `http(s)`, donc rien dans sa forme ne les
16
+ * distingue. Laisser l'hôte deviner le ferait ouvrir sa WebView sur ce qu'on
17
+ * lui montre, ce qu'ADR-036 refuse déjà pour la saisie. Le lien le dit.
18
+ */
19
+ const PAIRING_CHANNEL_PARAMETER = 'channel';
20
+ /**
21
+ * Le lien que porte le QR : l'adresse du serveur, telle que le conteneur la
22
+ * composera ensuite.
23
+ *
24
+ * L'adresse n'est pas encodée. `:` et `/` sont permis dans une query, et un
25
+ * `%3A` de plus par caractère ferait grossir le QR pour rien — une adresse de
26
+ * serveur de développement ne porte ni `&` ni `=`.
27
+ *
28
+ * La barre oblique avant la query n'est pas décorative : un lien au chemin vide
29
+ * se lit différemment d'un cadre d'hôte à l'autre, et plusieurs n'en tirent
30
+ * alors aucune route.
31
+ */
32
+ export function pairingDeepLink(baseUrl) {
33
+ return `${PAIRING_SCHEME}://${PAIRING_ACTION}/?${PAIRING_URL_PARAMETER}=${baseUrl}`;
34
+ }
35
+ /**
36
+ * Le lien que porte le QR d'un canal de développement : l'adresse que
37
+ * l'appareil interrogera (ADR-038).
38
+ *
39
+ * Même forme et mêmes raisons que celle d'un serveur local, au paramètre près.
40
+ * Le code court reste la voie sans appareil photo ; ce lien est celle qui
41
+ * épargne de le recopier.
42
+ */
43
+ export function channelDeepLink(pollUrl) {
44
+ return `${PAIRING_SCHEME}://${PAIRING_ACTION}/?${PAIRING_CHANNEL_PARAMETER}=${pollUrl}`;
45
+ }
@@ -0,0 +1,12 @@
1
+ /** Le document que le conteneur demande, et le seul que l'archive embarque. */
2
+ export declare const ENTRY_DOCUMENT = "index.html";
3
+ /** Le document que `mini dev` sert au navigateur, avec son mock natif. */
4
+ export declare const DEV_SHELL_FILE = "dev.html";
5
+ export declare const DEV_HOST_ENTRY = "dev-host";
6
+ export declare const DEV_CLIENT_ENTRY = "dev-client";
7
+ /**
8
+ * L'échafaudage que `mini dev` sert dans le navigateur. Il reste dans `outDir`,
9
+ * mais l'archive part sur le serveur de distribution et jusque sur les
10
+ * appareils : elle n'embarque que ce que le conteneur exécute.
11
+ */
12
+ export declare const DEV_SCAFFOLD_FILES: ReadonlySet<string>;
@@ -0,0 +1,16 @@
1
+ /** Le document que le conteneur demande, et le seul que l'archive embarque. */
2
+ export const ENTRY_DOCUMENT = 'index.html';
3
+ /** Le document que `mini dev` sert au navigateur, avec son mock natif. */
4
+ export const DEV_SHELL_FILE = 'dev.html';
5
+ export const DEV_HOST_ENTRY = 'dev-host';
6
+ export const DEV_CLIENT_ENTRY = 'dev-client';
7
+ /**
8
+ * L'échafaudage que `mini dev` sert dans le navigateur. Il reste dans `outDir`,
9
+ * mais l'archive part sur le serveur de distribution et jusque sur les
10
+ * appareils : elle n'embarque que ce que le conteneur exécute.
11
+ */
12
+ export const DEV_SCAFFOLD_FILES = new Set([
13
+ DEV_SHELL_FILE,
14
+ `${DEV_HOST_ENTRY}.js`,
15
+ `${DEV_CLIENT_ENTRY}.js`,
16
+ ]);
@@ -6,8 +6,25 @@ export interface DevServerOptions {
6
6
  }
7
7
  export interface DevServer {
8
8
  readonly url: string;
9
+ /**
10
+ * Les mêmes pages, atteintes depuis le réseau local : `listen` sans hôte
11
+ * écoute déjà toutes les interfaces, un appareil du même Wi-Fi y répond donc
12
+ * sans rien de plus. Vide sur une machine sans interface externe.
13
+ *
14
+ * Elles portent le jeton, parce qu'elles en ont besoin pour répondre.
15
+ */
16
+ readonly networkUrls: readonly string[];
17
+ /** Le jeton que ce serveur exige de tout appareil qui n'est pas la machine. */
18
+ readonly pairingToken: string;
9
19
  close(): void;
10
20
  }
21
+ /**
22
+ * Le type MIME d'un fichier servi, `application/octet-stream` à défaut.
23
+ *
24
+ * Exporté parce que le canal de développement doit étiqueter les mêmes
25
+ * fichiers (ADR-038) : deux tables divergeraient.
26
+ */
27
+ export declare function contentTypeFor(filePath: string): string;
11
28
  /**
12
29
  * Serveur `mini dev` : sert le bundle compilé, surveille les sources du
13
30
  * mini-programme et pousse un événement SSE de rechargement après chaque
@@ -1,7 +1,17 @@
1
1
  import { existsSync, watch } from 'node:fs';
2
2
  import { readFile } from 'node:fs/promises';
3
3
  import http from 'node:http';
4
+ import os from 'node:os';
4
5
  import path from 'node:path';
6
+ import { DEV_CLIENT_ENTRY, DEV_SHELL_FILE, ENTRY_DOCUMENT } from "./dev-scaffold.js";
7
+ import { dialableAddresses } from "./local-addresses.js";
8
+ import { mintPairingToken, pairingPathPrefix, pairingRefusal, splitPairingToken, } from "./pairing-token.js";
9
+ class DevServerError extends Error {
10
+ constructor(message) {
11
+ super(message);
12
+ this.name = 'DevServerError';
13
+ }
14
+ }
5
15
  const CONTENT_TYPES = {
6
16
  '.html': 'text/html; charset=utf-8',
7
17
  '.js': 'text/javascript; charset=utf-8',
@@ -17,7 +27,52 @@ const CONTENT_TYPES = {
17
27
  '.woff': 'font/woff',
18
28
  '.zip': 'application/zip',
19
29
  };
30
+ /**
31
+ * Le type MIME d'un fichier servi, `application/octet-stream` à défaut.
32
+ *
33
+ * Exporté parce que le canal de développement doit étiqueter les mêmes
34
+ * fichiers (ADR-038) : deux tables divergeraient.
35
+ */
36
+ export function contentTypeFor(filePath) {
37
+ return CONTENT_TYPES[path.extname(filePath)] ?? 'application/octet-stream';
38
+ }
20
39
  const REBUILD_DEBOUNCE_MS = 150;
40
+ const RELOAD_ENDPOINT = '/__cadence_dev';
41
+ /**
42
+ * Combien de fois le mini-programme a été recompilé depuis le démarrage.
43
+ *
44
+ * Un conteneur qui sert ses octets lui-même n'a pas de page où brancher le
45
+ * canal poussé : la WebView ne parle qu'à lui, et il ne sait pas tenir un flux
46
+ * ouvert à travers son interception de requêtes. Il demande donc ce compteur, et
47
+ * recharge quand il change (ADR-035).
48
+ */
49
+ const BUILD_COUNT_ENDPOINT = `${RELOAD_ENDPOINT}/builds`;
50
+ /**
51
+ * Ce que la page raconte sur l'appareil, rapporté ici.
52
+ *
53
+ * Un GET, et non un envoi : le seul HTTP dont un conteneur dispose est celui
54
+ * que le SDK lui injecte, et ce point d'injection rapporte des octets. Lui
55
+ * adjoindre un verbe demanderait un client par plateforme, pour une ligne de
56
+ * journal sur une machine locale (ADR-037).
57
+ */
58
+ const CONSOLE_ENDPOINT = `${RELOAD_ENDPOINT}/console`;
59
+ const CONSOLE_PARAMETER = 'line';
60
+ const DEVICE_PREFIX = '[appareil]';
61
+ const LONGEST_CONSOLE_LINE = 2000;
62
+ const BODY_END = '</body>';
63
+ const LIVE_RELOAD_TAG = `<script src="./${DEV_CLIENT_ENTRY}.js"></script>`;
64
+ /**
65
+ * Le conteneur demande le document de production, celui que l'archive embarque
66
+ * et qui ne porte aucun échafaudage. Le rechargement lui vient donc du serveur,
67
+ * à la seconde où il sert la page, et non du bundle : ce qui tourne sur
68
+ * l'appareil reste octet pour octet ce qui sera publié.
69
+ */
70
+ function withLiveReloadClient(document) {
71
+ if (!document.includes(BODY_END)) {
72
+ throw new DevServerError(`${ENTRY_DOCUMENT} ne contient pas ${BODY_END} : impossible d'y brancher le rechargement`);
73
+ }
74
+ return document.replace(BODY_END, ` ${LIVE_RELOAD_TAG}\n ${BODY_END}`);
75
+ }
21
76
  /**
22
77
  * Serveur `mini dev` : sert le bundle compilé, surveille les sources du
23
78
  * mini-programme et pousse un événement SSE de rechargement après chaque
@@ -25,12 +80,55 @@ const REBUILD_DEBOUNCE_MS = 150;
25
80
  */
26
81
  export function startDevServer(options) {
27
82
  const sseClients = new Set();
83
+ const pairingToken = mintPairingToken();
84
+ let completedBuilds = 0;
85
+ const servedRoot = options.distDir.endsWith(path.sep)
86
+ ? options.distDir
87
+ : `${options.distDir}${path.sep}`;
28
88
  const server = http.createServer((request, response) => {
29
- void handleRequest(request, response);
89
+ handleRequest(request, response).catch((error) => {
90
+ const message = error instanceof Error ? error.message : String(error);
91
+ console.error('[cadence dev]', message);
92
+ if (!response.headersSent) {
93
+ response.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
94
+ }
95
+ response.end(`500 — ${message}`);
96
+ });
30
97
  });
31
98
  async function handleRequest(request, response) {
32
- const url = (request.url ?? '/').split('?')[0] ?? '/';
33
- if (url === '/__cadence_dev') {
99
+ const [requestPath = '/', query = ''] = (request.url ?? '/').split('?');
100
+ const requested = splitPairingToken(requestPath);
101
+ const refusal = pairingRefusal({
102
+ expected: pairingToken,
103
+ presented: requested.token,
104
+ peer: request.socket.remoteAddress,
105
+ });
106
+ if (refusal !== null) {
107
+ response.writeHead(403, { 'Content-Type': 'text/plain; charset=utf-8' });
108
+ response.end(`403 — ${refusal}`);
109
+ return;
110
+ }
111
+ if (requested.path === CONSOLE_ENDPOINT) {
112
+ const line = new URLSearchParams(query).get(CONSOLE_PARAMETER) ?? '';
113
+ console.warn(`${DEVICE_PREFIX} ${line.slice(0, LONGEST_CONSOLE_LINE)}`);
114
+ /* 200 et non 204 : le conteneur lit par le téléchargeur du SDK, qui
115
+ refuse tout ce qui n'est pas un corps complet. */
116
+ response.writeHead(200, {
117
+ 'Content-Type': 'text/plain; charset=utf-8',
118
+ 'Cache-Control': 'no-store',
119
+ });
120
+ response.end('ok');
121
+ return;
122
+ }
123
+ if (requested.path === BUILD_COUNT_ENDPOINT) {
124
+ response.writeHead(200, {
125
+ 'Content-Type': 'text/plain; charset=utf-8',
126
+ 'Cache-Control': 'no-store',
127
+ });
128
+ response.end(String(completedBuilds));
129
+ return;
130
+ }
131
+ if (requested.path === RELOAD_ENDPOINT) {
34
132
  response.writeHead(200, {
35
133
  'Content-Type': 'text/event-stream',
36
134
  'Cache-Control': 'no-cache',
@@ -41,16 +139,21 @@ export function startDevServer(options) {
41
139
  request.on('close', () => sseClients.delete(response));
42
140
  return;
43
141
  }
44
- const relativePath = url === '/' ? 'dev.html' : url.slice(1);
142
+ const relativePath = requested.path === '/' ? DEV_SHELL_FILE : requested.path.slice(1);
45
143
  const filePath = path.join(options.distDir, relativePath);
46
- if (!filePath.startsWith(options.distDir) || !existsSync(filePath)) {
144
+ if (!filePath.startsWith(servedRoot) || !existsSync(filePath)) {
47
145
  response.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
48
146
  response.end(`404 — ${relativePath}`);
49
147
  return;
50
148
  }
51
- const contentType = CONTENT_TYPES[path.extname(filePath)] ?? 'application/octet-stream';
149
+ /* Le corps est prêt avant l'en-tête : un document d'entrée où brancher le
150
+ rechargement échoue répond 500, et non 200 suivi d'un silence. */
151
+ const body = relativePath === ENTRY_DOCUMENT
152
+ ? withLiveReloadClient(await readFile(filePath, 'utf8'))
153
+ : await readFile(filePath);
154
+ const contentType = contentTypeFor(filePath);
52
155
  response.writeHead(200, { 'Content-Type': contentType, 'Cache-Control': 'no-store' });
53
- response.end(await readFile(filePath));
156
+ response.end(body);
54
157
  }
55
158
  let rebuildTimer = null;
56
159
  const watcher = watch(options.watchDir, { recursive: true }, (_event, fileName) => {
@@ -64,6 +167,7 @@ export function startDevServer(options) {
64
167
  options
65
168
  .rebuild()
66
169
  .then(() => {
170
+ completedBuilds += 1;
67
171
  console.warn(`[cadence dev] rebuild ok (${fileName ?? 'watch'})`);
68
172
  for (const client of sseClients) {
69
173
  client.write('event: reload\ndata: {}\n\n');
@@ -75,6 +179,8 @@ export function startDevServer(options) {
75
179
  server.listen(options.port);
76
180
  return {
77
181
  url: `http://localhost:${options.port}/`,
182
+ networkUrls: dialableAddresses(os.networkInterfaces()).map((host) => `http://${host}:${options.port}${pairingPathPrefix(pairingToken)}`),
183
+ pairingToken,
78
184
  close() {
79
185
  watcher.close();
80
186
  for (const client of sseClients) {
@@ -144,6 +144,9 @@ host.handle(BridgeMethods.appReportError, (payload) => {
144
144
  console.error(`[cadence miniapp] ${source} — ${message}`, stack ?? '');
145
145
  return null;
146
146
  });
147
+ /* Un navigateur n'a pas d'écran d'ouverture à lever. L'appel est tout de même
148
+ accepté : un refus ferait écrire au moteur une erreur qui n'en est pas une. */
149
+ host.handle(BridgeMethods.appPageRendered, () => null);
147
150
  host.handle(BridgeMethods.navSetChrome, (payload) => {
148
151
  document.title = payload.title;
149
152
  return null;
@@ -1,5 +1,7 @@
1
1
  "use strict";
2
- const events = new EventSource('/__cadence_dev');
2
+ /* Relative, et non absolue : l'adresse d'un appareil apparié porte un
3
+ préfixe de jeton, que le calcul du navigateur reconduit tout seul. */
4
+ const events = new EventSource('./__cadence_dev');
3
5
  events.addEventListener('reload', () => location.reload());
4
6
  events.addEventListener('error', () => {
5
7
  /* le serveur dev est parti ; EventSource retentera tout seul */
@@ -110,6 +110,40 @@ function announceEntryChrome(nativeApi, manifest) {
110
110
  console.error('[cadence] the container did not take the entry chrome', error);
111
111
  });
112
112
  }
113
+ /**
114
+ * Dit au conteneur que la page d'entrée est peinte, et une seule fois.
115
+ *
116
+ * C'est le signal qui lève un écran d'ouverture. `nav.setChrome` part **avant**
117
+ * le rendu — un conteneur qui s'en sert découvre une WebView encore vide.
118
+ */
119
+ function announcePageRendered(nativeApi) {
120
+ afterTheNextPaint(() => {
121
+ /* Un conteneur qui ne connaît pas la méthode rejette l'appel, et c'est son
122
+ droit : le moteur n'a rien à faire de la réponse. */
123
+ void nativeApi.app.pageRendered().catch(() => undefined);
124
+ });
125
+ }
126
+ /**
127
+ * Appelle `onPainted` une fois la frame suivante passée à l'écran.
128
+ *
129
+ * Le rappel de `requestAnimationFrame` s'exécute **avant** la peinture de sa
130
+ * frame ; la tâche qu'il programme s'exécute après. C'est la seule façon
131
+ * d'attendre le pixel sans le mesurer.
132
+ *
133
+ * Un document déjà caché n'ordonnance aucune frame, et le repli part alors sur
134
+ * une tâche : le conteneur garderait sinon son écran d'ouverture pour toujours.
135
+ * Rien ne clignote pour autant — une vue qu'on ne regarde pas peint sa page
136
+ * avant qu'on la regarde.
137
+ */
138
+ function afterTheNextPaint(onPainted) {
139
+ if (typeof requestAnimationFrame !== 'function' || document.hidden) {
140
+ setTimeout(onPainted, 0);
141
+ return;
142
+ }
143
+ requestAnimationFrame(() => {
144
+ setTimeout(onPainted, 0);
145
+ });
146
+ }
113
147
  function resolveAppRoot() {
114
148
  const existing = document.getElementById('app');
115
149
  if (existing !== null) {
@@ -185,6 +219,7 @@ async function startEngine(manifest, app) {
185
219
  setActiveRouter(appRouter);
186
220
  await appRouter.launch();
187
221
  metrics.timeToInteractiveMs = performance.now();
222
+ announcePageRendered(nativeApi);
188
223
  }
189
224
  const cadenceGlobal = {
190
225
  version: ENGINE_VERSION,
package/dist/index.d.ts CHANGED
@@ -17,8 +17,12 @@ export { projectToolingFiles } from './project-tooling.js';
17
17
  export type { InitOptions, InitReport } from './init-project.js';
18
18
  export { PROJECT_TEMPLATES, PROJECT_TEMPLATE_NAMES, isProjectTemplateName, } from './project-templates.js';
19
19
  export type { ProjectTemplate, ProjectTemplateName } from './project-templates.js';
20
- export { startDevServer } from './dev-server.js';
20
+ export { startDevServer, contentTypeFor } from './dev-server.js';
21
21
  export type { DevServer, DevServerOptions } from './dev-server.js';
22
+ export { DevChannelClient, DevChannelRejectedError } from './dev-channel-client.js';
23
+ export type { DevChannelClientOptions, OpenedDevChannel, PushedBundle, } from './dev-channel-client.js';
24
+ export { openDevChannel } from './dev-channel-session.js';
25
+ export type { DevChannelPush, DevChannelSession, OpenDevChannelOptions, } from './dev-channel-session.js';
22
26
  export { credentialsPath, readCredentials, writeCredentials, clearCredentials, normalizeRemoteUrl, } from './publish/credentials.js';
23
27
  export type { Credentials } from './publish/credentials.js';
24
28
  export { DistributionClient } from './publish/distribution-client.js';
package/dist/index.js CHANGED
@@ -10,7 +10,9 @@ export { buildMiniApp, BuildError } from "./build.js";
10
10
  export { initProject, InitError } from "./init-project.js";
11
11
  export { projectToolingFiles } from "./project-tooling.js";
12
12
  export { PROJECT_TEMPLATES, PROJECT_TEMPLATE_NAMES, isProjectTemplateName, } from "./project-templates.js";
13
- export { startDevServer } from "./dev-server.js";
13
+ export { startDevServer, contentTypeFor } from "./dev-server.js";
14
+ export { DevChannelClient, DevChannelRejectedError } from "./dev-channel-client.js";
15
+ export { openDevChannel } from "./dev-channel-session.js";
14
16
  export { credentialsPath, readCredentials, writeCredentials, clearCredentials, normalizeRemoteUrl, } from "./publish/credentials.js";
15
17
  export { DistributionClient } from "./publish/distribution-client.js";
16
18
  export { publishMiniApp } from "./publish/publish-bundle.js";
@@ -0,0 +1,10 @@
1
+ import type { NetworkInterfaceInfo } from 'node:os';
2
+ /**
3
+ * Les adresses IPv4 de cette machine qu'un autre appareil peut composer.
4
+ *
5
+ * Deux refus. Une interface interne ne sort pas de la machine. Et une adresse
6
+ * dont les bits d'hôte sont tous nuls désigne le réseau, pas une machine :
7
+ * macOS en expose une par pont de partage, et elles noieraient la seule
8
+ * adresse utile.
9
+ */
10
+ export declare function dialableAddresses(interfaces: Readonly<Record<string, NetworkInterfaceInfo[] | undefined>>): readonly string[];
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Les adresses IPv4 de cette machine qu'un autre appareil peut composer.
3
+ *
4
+ * Deux refus. Une interface interne ne sort pas de la machine. Et une adresse
5
+ * dont les bits d'hôte sont tous nuls désigne le réseau, pas une machine :
6
+ * macOS en expose une par pont de partage, et elles noieraient la seule
7
+ * adresse utile.
8
+ */
9
+ export function dialableAddresses(interfaces) {
10
+ return Object.values(interfaces)
11
+ .flatMap((addresses) => addresses ?? [])
12
+ .filter((address) => address.family === 'IPv4' && !address.internal)
13
+ .filter((address) => !isNetworkAddress(address.address, address.netmask))
14
+ .map((address) => address.address);
15
+ }
16
+ function isNetworkAddress(address, netmask) {
17
+ const host = toUnsignedInteger(address);
18
+ const network = (host & toUnsignedInteger(netmask)) >>> 0;
19
+ return network === host;
20
+ }
21
+ function toUnsignedInteger(dotted) {
22
+ return dotted.split('.').reduce((value, byte) => value * 256 + Number(byte), 0);
23
+ }
@@ -0,0 +1,40 @@
1
+ /** Ce qu'un chemin demandait, une fois son jeton mis de côté. */
2
+ export interface PairedRequest {
3
+ /** Le jeton que le chemin portait, ou `null` s'il n'en portait pas. */
4
+ readonly token: string | null;
5
+ /** Le chemin sans son préfixe, celui que le serveur résout. */
6
+ readonly path: string;
7
+ }
8
+ /** Une requête à juger : le jeton attendu, celui présenté, et d'où elle vient. */
9
+ export interface PairingCheck {
10
+ readonly expected: string;
11
+ readonly presented: string | null;
12
+ readonly peer: string | undefined;
13
+ }
14
+ /**
15
+ * Un jeton d'appariement, neuf à chaque `mini dev`.
16
+ *
17
+ * Il ne protège rien d'autre que des sources en cours d'écriture, et il meurt
18
+ * avec le serveur : le tirage vaut pour un réseau partagé, pas pour un secret
19
+ * qu'on garde.
20
+ */
21
+ export declare function mintPairingToken(): string;
22
+ /** Le préfixe de chemin qui porte ce jeton, barre oblique finale comprise. */
23
+ export declare function pairingPathPrefix(token: string): string;
24
+ /**
25
+ * Sépare le jeton du chemin qu'il préfixe.
26
+ *
27
+ * Le jeton vit dans le chemin, et non dans un en-tête ni une query : le
28
+ * conteneur compose l'adresse d'un sous-fichier en ajoutant son nom à celle du
29
+ * document, et un préfixe suit ce calcul sans que personne n'ait à le savoir.
30
+ */
31
+ export declare function splitPairingToken(requestPath: string): PairedRequest;
32
+ /**
33
+ * Pourquoi cette requête est refusée, `null` quand elle passe.
34
+ *
35
+ * La machine elle-même n'a rien à présenter : le navigateur et l'USB gardent
36
+ * l'adresse courte qu'annonce la documentation. Le jeton n'est exigé que de ce
37
+ * que la boucle locale n'explique pas — un appareil du Wi-Fi, donc aussi la
38
+ * machine du voisin.
39
+ */
40
+ export declare function pairingRefusal(check: PairingCheck): string | null;
@@ -0,0 +1,76 @@
1
+ import { randomBytes } from 'node:crypto';
2
+ /** Le segment qui annonce un jeton dans un chemin : `/t/<jeton>/index.html`. */
3
+ const TOKEN_SEGMENT = 't';
4
+ const TOKEN_LENGTH = 12;
5
+ /*
6
+ * Trente-deux caractères, sans les jumeaux qu'on recopie de travers (0 et O,
7
+ * 1 et l) : le jeton se tape à la main quand lire un QR n'est pas une option.
8
+ * Trente-deux divise 256, donc tirer un octet modulo l'alphabet ne favorise
9
+ * aucun caractère.
10
+ */
11
+ const TOKEN_ALPHABET = '0123456789abcdefghjkmnpqrstvwxyz';
12
+ const IPV4_IN_IPV6_PREFIX = '::ffff:';
13
+ /**
14
+ * Un jeton d'appariement, neuf à chaque `mini dev`.
15
+ *
16
+ * Il ne protège rien d'autre que des sources en cours d'écriture, et il meurt
17
+ * avec le serveur : le tirage vaut pour un réseau partagé, pas pour un secret
18
+ * qu'on garde.
19
+ */
20
+ export function mintPairingToken() {
21
+ return Array.from(randomBytes(TOKEN_LENGTH), (byte) => TOKEN_ALPHABET.charAt(byte % TOKEN_ALPHABET.length)).join('');
22
+ }
23
+ /** Le préfixe de chemin qui porte ce jeton, barre oblique finale comprise. */
24
+ export function pairingPathPrefix(token) {
25
+ return `/${TOKEN_SEGMENT}/${token}/`;
26
+ }
27
+ /**
28
+ * Sépare le jeton du chemin qu'il préfixe.
29
+ *
30
+ * Le jeton vit dans le chemin, et non dans un en-tête ni une query : le
31
+ * conteneur compose l'adresse d'un sous-fichier en ajoutant son nom à celle du
32
+ * document, et un préfixe suit ce calcul sans que personne n'ait à le savoir.
33
+ */
34
+ export function splitPairingToken(requestPath) {
35
+ const segments = requestPath.split('/');
36
+ const token = segments[2];
37
+ if (segments[1] !== TOKEN_SEGMENT || token === undefined || token === '') {
38
+ return { token: null, path: requestPath };
39
+ }
40
+ return { token, path: `/${segments.slice(3).join('/')}` };
41
+ }
42
+ /**
43
+ * Pourquoi cette requête est refusée, `null` quand elle passe.
44
+ *
45
+ * La machine elle-même n'a rien à présenter : le navigateur et l'USB gardent
46
+ * l'adresse courte qu'annonce la documentation. Le jeton n'est exigé que de ce
47
+ * que la boucle locale n'explique pas — un appareil du Wi-Fi, donc aussi la
48
+ * machine du voisin.
49
+ */
50
+ export function pairingRefusal(check) {
51
+ if (check.presented === check.expected) {
52
+ return null;
53
+ }
54
+ if (check.presented !== null) {
55
+ return "jeton d'appariement inconnu — relire celui qu'affiche « mini dev »";
56
+ }
57
+ if (isLoopbackPeer(check.peer)) {
58
+ return null;
59
+ }
60
+ return "un appareil du réseau doit porter le jeton d'appariement de « mini dev »";
61
+ }
62
+ /**
63
+ * Vrai quand la requête vient de cette machine.
64
+ *
65
+ * L'USB en fait partie : `adb reverse` fait composer 127.0.0.1 au téléphone, et
66
+ * c'est le tunnel qui livre.
67
+ */
68
+ function isLoopbackPeer(address) {
69
+ if (address === undefined) {
70
+ return false;
71
+ }
72
+ const bare = address.startsWith(IPV4_IN_IPV6_PREFIX)
73
+ ? address.slice(IPV4_IN_IPV6_PREFIX.length)
74
+ : address;
75
+ return bare === '::1' || bare.startsWith('127.');
76
+ }
@@ -0,0 +1,9 @@
1
+ /** Le produit de deux octets dans GF(2⁸). */
2
+ export declare function multiplyInGf256(left: number, right: number): number;
3
+ /**
4
+ * Le polynôme générateur de ce nombre de codets de correction, privé de son
5
+ * coefficient de tête — il vaut toujours un, et la division ne s'en sert pas.
6
+ */
7
+ export declare function generatorTail(degree: number): Uint8Array;
8
+ /** Les codets de correction de ce bloc de données, par division polynomiale. */
9
+ export declare function errorCorrectionFor(data: Uint8Array, tail: Uint8Array): Uint8Array;
@@ -0,0 +1,48 @@
1
+ /*
2
+ * L'arithmétique du corps fini que la norme QR fixe (ISO/IEC 18004, § 7.5) :
3
+ * GF(2⁸) réduit par x⁸ + x⁴ + x³ + x² + 1. Rien ici n'est un choix — ces
4
+ * constantes sont celles qu'un lecteur attend, et toute autre rendrait le code
5
+ * illisible par une caméra.
6
+ */
7
+ const REDUCING_POLYNOMIAL = 0x11d;
8
+ const PRIMITIVE_ELEMENT = 0x02;
9
+ /** Le produit de deux octets dans GF(2⁸). */
10
+ export function multiplyInGf256(left, right) {
11
+ let product = 0;
12
+ for (let bit = 7; bit >= 0; bit -= 1) {
13
+ product = (product << 1) ^ ((product >>> 7) * REDUCING_POLYNOMIAL);
14
+ product ^= ((right >>> bit) & 1) * left;
15
+ }
16
+ return product & 0xff;
17
+ }
18
+ /**
19
+ * Le polynôme générateur de ce nombre de codets de correction, privé de son
20
+ * coefficient de tête — il vaut toujours un, et la division ne s'en sert pas.
21
+ */
22
+ export function generatorTail(degree) {
23
+ const tail = new Uint8Array(degree);
24
+ tail[degree - 1] = 1;
25
+ let root = 1;
26
+ for (let step = 0; step < degree; step += 1) {
27
+ for (let index = 0; index < degree; index += 1) {
28
+ const scaled = multiplyInGf256(tail[index] ?? 0, root);
29
+ const carried = index + 1 < degree ? (tail[index + 1] ?? 0) : 0;
30
+ tail[index] = scaled ^ carried;
31
+ }
32
+ root = multiplyInGf256(root, PRIMITIVE_ELEMENT);
33
+ }
34
+ return tail;
35
+ }
36
+ /** Les codets de correction de ce bloc de données, par division polynomiale. */
37
+ export function errorCorrectionFor(data, tail) {
38
+ const remainder = new Uint8Array(tail.length);
39
+ for (const byte of data) {
40
+ const factor = byte ^ (remainder[0] ?? 0);
41
+ remainder.copyWithin(0, 1);
42
+ remainder[remainder.length - 1] = 0;
43
+ for (let index = 0; index < tail.length; index += 1) {
44
+ remainder[index] = (remainder[index] ?? 0) ^ multiplyInGf256(tail[index] ?? 0, factor);
45
+ }
46
+ }
47
+ return remainder;
48
+ }
@@ -0,0 +1,9 @@
1
+ /** Une matrice de QR code, ligne par ligne : `true` pour un module sombre. */
2
+ export type QrMatrix = readonly (readonly boolean[])[];
3
+ /**
4
+ * Dessine la matrice de cette version à partir de ses codets, masque compris.
5
+ *
6
+ * Les codets arrivent déjà entrelacés et complétés de leur correction : ce qui
7
+ * reste est purement géométrique.
8
+ */
9
+ export declare function drawQrMatrix(codewords: Uint8Array, version: number): QrMatrix;