@serfab/cadre-core 1.14.0 → 1.15.0

package/dist/cadre-join-request.d.ts

@@ -0,0 +1,42 @@
+/** Version 1 of the join request; the only one either side reads. */
+export declare const CADRE_JOIN_REQUEST_PREFIX = "sereus-join-request:1.";
+/**
+ * Version 1 of an encoded cadre invitation (`encodeCadreInvitation`). Declared here, beside
+ * the request's prefix, so each decoder can name the other kind of text when it is pasted in
+ * the wrong place without this codec importing the redemption protocol.
+ */
+export declare const CADRE_INVITATION_PREFIX = "sereus-invite:1.";
+/** Longest `appName` a request carries: one line in an approval prompt. */
+export declare const CADRE_JOIN_REQUEST_MAX_APP_NAME = 64;
+/** Where and how the owner app answers a request that arrived as a link. */
+export interface CadreJoinReply {
+    /** The requesting app's own custom URL scheme; the owner app opens `<scheme>://cadre-join-response/<response>`. */
+    scheme: string;
+    /** Echoed in the response, so the requesting app takes only an answer to a request it has open. */
+    nonce: string;
+}
+export interface CadreJoinRequest {
+    v: 1;
+    /** The requesting node's peer id: an Ed25519 peer id, since the invitation targets that key. */
+    peerId: string;
+    /** What the requester calls itself, for the owner's approval prompt. Unverified; at most 64 characters, trimmed, non-empty. */
+    appName: string;
+    /** Present only on a request opened as a link: where and how the owner app answers. */
+    reply?: CadreJoinReply;
+}
+/** Encode a request as the text the requesting app copies. Refuses what {@link decodeCadreJoinRequest} would. */
+export declare function encodeCadreJoinRequest(request: CadreJoinRequest): string;
+/**
+ * Decode the text the owner's app was given. Refuses, naming the problem: an invitation
+ * pasted here, any prefix but version 1's, a body that is not base64url JSON of the request's
+ * shape, a peer id that does not parse or is not Ed25519, an `appName` that is empty or
+ * longer than {@link CADRE_JOIN_REQUEST_MAX_APP_NAME} characters once trimmed, and a `reply`
+ * that {@link requireCadreJoinReply} refuses.
+ */
+export declare function decodeCadreJoinRequest(text: string): CadreJoinRequest;
+/**
+ * Refuses, naming the problem, a reply whose scheme is not a lowercase URL scheme of at most 64
+ * characters or is a web or system scheme (`https`, `file`, `intent`, …), and a nonce that is
+ * not 16 to 64 base64url characters. The owner app checks it again before it opens a reply.
+ */
+export declare function requireCadreJoinReply(reply: CadreJoinReply): CadreJoinReply;

package/dist/cadre-join-request.js

@@ -0,0 +1,144 @@
+/**
+ * The join request: the text an app that wants to join a cadre copies (or shows as a QR code)
+ * so the app that manages the cadre can mint an invitation for it alone
+ * (`CadreNode.createCadreInvitation({ peerId: request.peerId, grantsOwner })`).
+ *
+ * `sereus-join-request:1.<base64url of canonical JSON>` where the JSON is
+ * `{ appName, peerId, reply?, v }`. Nothing in it is secret or signed: the peer id is public, and
+ * the name is only what the requester calls itself, shown in the owner's approval prompt. The
+ * safety is in the response: an invitation targeted at that peer id can be redeemed only by
+ * the key behind it.
+ *
+ * `reply` is present only on a request opened as a link from another app on the same phone
+ * (`@serfab/cadre-rn/app-link`): the owner app answers by opening `<reply.scheme>://…`, a link it
+ * builds itself, so the scheme is restricted to an app's own custom scheme and never a web or
+ * system one, which would send the invitation's machine addresses off the phone.
+ *
+ * Imports only `@libp2p/peer-id` and `uint8arrays`, so it loads on React Native and in the
+ * browser.
+ */
+import { peerIdFromString } from '@libp2p/peer-id';
+import { fromString as uint8ArrayFromString, toString as uint8ArrayToString } from 'uint8arrays';
+import { canonicalJson } from './canonical-json.js';
+/** Version 1 of the join request; the only one either side reads. */
+export const CADRE_JOIN_REQUEST_PREFIX = 'sereus-join-request:1.';
+/**
+ * Version 1 of an encoded cadre invitation (`encodeCadreInvitation`). Declared here, beside
+ * the request's prefix, so each decoder can name the other kind of text when it is pasted in
+ * the wrong place without this codec importing the redemption protocol.
+ */
+export const CADRE_INVITATION_PREFIX = 'sereus-invite:1.';
+/** Longest `appName` a request carries: one line in an approval prompt. */
+export const CADRE_JOIN_REQUEST_MAX_APP_NAME = 64;
+/**
+ * Schemes a reply may not name, though they match {@link CADRE_JOIN_REPLY_SCHEME}: each opens a
+ * web page, a file, a system action or another app's content rather than a Sereus app.
+ */
+const REFUSED_REPLY_SCHEMES = new Set([
+    'http', 'https', 'ws', 'wss', 'ftp', 'file', 'content', 'data', 'blob',
+    'javascript', 'about', 'intent', 'mailto', 'tel', 'sms',
+]);
+/**
+ * The form of a reply's scheme: lowercase, as an app's custom URL scheme is declared.
+ * NOTE: `@serfab/cadre-rn`'s CommonJS config plugin keeps a copy (`APP_SCHEME`) to check extra
+ * apps' schemes; change it with this one.
+ */
+const CADRE_JOIN_REPLY_SCHEME = /^[a-z][a-z0-9+.-]{0,63}$/;
+/** The form of a reply's nonce: base64url, long enough that it cannot be guessed. */
+const CADRE_JOIN_REPLY_NONCE = /^[A-Za-z0-9_-]{16,64}$/;
+/** Encode a request as the text the requesting app copies. Refuses what {@link decodeCadreJoinRequest} would. */
+export function encodeCadreJoinRequest(request) {
+    const checked = requireCadreJoinRequest(request);
+    // canonicalJson drops an undefined `reply`, so a request without one encodes as it always has.
+    const json = canonicalJson({ appName: checked.appName, peerId: checked.peerId, reply: checked.reply, v: checked.v });
+    return `${CADRE_JOIN_REQUEST_PREFIX}${uint8ArrayToString(new TextEncoder().encode(json), 'base64url')}`;
+}
+/**
+ * Decode the text the owner's app was given. Refuses, naming the problem: an invitation
+ * pasted here, any prefix but version 1's, a body that is not base64url JSON of the request's
+ * shape, a peer id that does not parse or is not Ed25519, an `appName` that is empty or
+ * longer than {@link CADRE_JOIN_REQUEST_MAX_APP_NAME} characters once trimmed, and a `reply`
+ * that {@link requireCadreJoinReply} refuses.
+ */
+export function decodeCadreJoinRequest(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith(CADRE_INVITATION_PREFIX)) {
+        throw new Error('This is a cadre invitation, not a join request; paste it where the app asks for an invitation');
+    }
+    if (!trimmed.startsWith(CADRE_JOIN_REQUEST_PREFIX)) {
+        throw new Error(`A join request must start with "${CADRE_JOIN_REQUEST_PREFIX}" (this one starts with "${trimmed.slice(0, CADRE_JOIN_REQUEST_PREFIX.length)}")`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(uint8ArrayFromString(trimmed.slice(CADRE_JOIN_REQUEST_PREFIX.length), 'base64url')));
+    }
+    catch (error) {
+        throw new Error('A join request must carry base64url-encoded JSON after its prefix', { cause: error });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('A join request must decode to a JSON object');
+    }
+    const { v, peerId, appName, reply } = parsed;
+    if (v !== 1)
+        throw new Error(`A join request must be version 1 (this one says ${JSON.stringify(v)})`);
+    if (typeof peerId !== 'string')
+        throw new Error('A join request must name the requesting node\'s peer id');
+    if (typeof appName !== 'string')
+        throw new Error('A join request must carry the requesting app\'s name');
+    return requireCadreJoinRequest({ v, peerId, appName, ...(reply === undefined ? {} : { reply: replyShape(reply) }) });
+}
+/**
+ * Refuses, naming the problem, a reply whose scheme is not a lowercase URL scheme of at most 64
+ * characters or is a web or system scheme (`https`, `file`, `intent`, …), and a nonce that is
+ * not 16 to 64 base64url characters. The owner app checks it again before it opens a reply.
+ */
+export function requireCadreJoinReply(reply) {
+    const { scheme, nonce } = reply;
+    if (!CADRE_JOIN_REPLY_SCHEME.test(scheme)) {
+        throw new Error(`A join request's reply scheme must be a lowercase URL scheme of at most 64 characters (this one is ${JSON.stringify(scheme)})`);
+    }
+    if (REFUSED_REPLY_SCHEMES.has(scheme)) {
+        throw new Error(`A join request's reply scheme must be an app's own scheme, not "${scheme}"`);
+    }
+    if (!CADRE_JOIN_REPLY_NONCE.test(nonce)) {
+        throw new Error('A join request\'s reply nonce must be 16 to 64 base64url characters');
+    }
+    return { scheme, nonce };
+}
+/** The decoded `reply`'s types, before {@link requireCadreJoinReply} judges its values. */
+function replyShape(reply) {
+    if (typeof reply !== 'object' || reply === null || Array.isArray(reply)) {
+        throw new Error('A join request\'s reply must be an object');
+    }
+    const { scheme, nonce } = reply;
+    if (typeof scheme !== 'string' || typeof nonce !== 'string') {
+        throw new Error('A join request\'s reply must carry a scheme and a nonce');
+    }
+    return { scheme, nonce };
+}
+/** The shape rules both directions apply. Returns the request with its fields trimmed. */
+function requireCadreJoinRequest(request) {
+    const peerId = requireEd25519PeerId(request.peerId);
+    const appName = request.appName.trim();
+    if (appName.length === 0)
+        throw new Error('A join request must name the requesting app');
+    if (appName.length > CADRE_JOIN_REQUEST_MAX_APP_NAME) {
+        throw new Error(`A join request's app name must be at most ${CADRE_JOIN_REQUEST_MAX_APP_NAME} characters (this one has ${appName.length})`);
+    }
+    return { v: 1, peerId, appName, ...(request.reply ? { reply: requireCadreJoinReply(request.reply) } : {}) };
+}
+/** An invitation targeted at the peer id names its key, so only an Ed25519 id could ever redeem one. */
+function requireEd25519PeerId(text) {
+    let parsed;
+    try {
+        parsed = peerIdFromString(text.trim());
+    }
+    catch (error) {
+        throw new Error(`A join request's peer id does not parse ("${text}")`, { cause: error });
+    }
+    if (parsed.type !== 'Ed25519') {
+        throw new Error(`A join request's peer id must be an Ed25519 peer id (this one is ${parsed.type})`);
+    }
+    return parsed.toString();
+}
+//# sourceMappingURL=cadre-join-request.js.map

package/dist/cadre-join-request.js.map

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