@peers-app/peers-sdk 0.23.13 → 0.24.0

package/dist/invites/invite-messages.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inviteEnvelopeSchema = exports.inviteMessageSchema = exports.inviteAcceptedSchema = exports.inviteDeclineSchema = exports.groupApprovalSchema = exports.groupJoinRequestSchema = exports.contactReplySchema = void 0;
+exports.sealInviteEnvelope = sealInviteEnvelope;
+exports.openInviteEnvelope = openInviteEnvelope;
+exports.inviteMessageSender = inviteMessageSender;
+const zod_1 = require("zod");
+const data_1 = require("../data");
+const keys_1 = require("../keys");
+const zod_types_1 = require("../types/zod-types");
+const data_box_schema_1 = require("./data-box-schema");
+const invite_token_1 = require("./invite-token");
+const base64UrlSchema = zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/);
+// Record schemas are resolved lazily so this module does not depend on the order in which
+// the `data` barrel finishes loading (it can be mid-load when this file is first imported).
+const lazyGroupSchema = zod_1.z.lazy(() => data_1.groupSchema);
+const lazyGroupMemberSchema = zod_1.z.lazy(() => data_1.groupMemberSchema);
+const lazyUserSchema = zod_1.z.lazy(() => data_1.userSchema);
+const lazyDeviceInfoSchema = zod_1.z.lazy(() => data_1.deviceInfoSchema);
+/** Recipient accepted a contact token; carries their identity back to the inviter. */
+exports.contactReplySchema = zod_1.z
+    .object({
+    kind: zod_1.z.literal("contact-reply"),
+    /** Nonce and epoch of the token that was accepted. */
+    inviteNonce: base64UrlSchema.length(22),
+    inviteEpoch: zod_1.z.number().int().min(0),
+    responder: invite_token_1.inviteIdentitySchema,
+    responderDeviceId: zod_types_1.zodPeerId,
+})
+    .strict();
+/** Joiner asks to be admitted under a group token (approve or open mode). */
+exports.groupJoinRequestSchema = zod_1.z
+    .object({
+    kind: zod_1.z.literal("group-join-request"),
+    token: invite_token_1.peersInviteSchema,
+    requester: invite_token_1.inviteIdentitySchema,
+    requesterDeviceId: zod_types_1.zodPeerId,
+})
+    .strict();
+/**
+ * Everything a joiner needs to enter a group: the group record, their signed membership,
+ * Admin+ seed rows, the approver's identity, and the group secret boxed to the joiner.
+ */
+exports.groupApprovalSchema = zod_1.z
+    .object({
+    kind: zod_1.z.literal("group-approval"),
+    /** Nonce of the token or direct invite this approval answers, when there is one. */
+    inviteNonce: base64UrlSchema.length(22).optional(),
+    group: lazyGroupSchema,
+    membership: lazyGroupMemberSchema,
+    seed: zod_1.z
+        .object({
+        groupMembers: zod_1.z.array(lazyGroupMemberSchema).max(20),
+        users: zod_1.z.array(lazyUserSchema).max(20),
+        devices: zod_1.z.array(lazyDeviceInfoSchema).max(20),
+    })
+        .strict(),
+    approver: invite_token_1.inviteIdentitySchema,
+    approverDeviceId: zod_types_1.zodPeerId,
+    /** Group encryption secret boxed to the joiner's `publicBoxKey`. */
+    boxedSecret: data_box_schema_1.dataBoxSchema,
+})
+    .strict();
+/** A party declined or denied an invite or join request. */
+exports.inviteDeclineSchema = zod_1.z
+    .object({
+    kind: zod_1.z.literal("invite-decline"),
+    inviteNonce: base64UrlSchema.length(22),
+    groupId: zod_types_1.zodPeerId.optional(),
+    by: invite_token_1.inviteIdentitySchema,
+    reason: zod_1.z.string().max(200).optional(),
+})
+    .strict();
+/**
+ * The recipient of a direct group invite or a profile-QR reply completed their side, so the
+ * other party can move its row from pending to accepted.
+ */
+exports.inviteAcceptedSchema = zod_1.z
+    .object({
+    kind: zod_1.z.literal("invite-accepted"),
+    inviteNonce: base64UrlSchema.length(22),
+    groupId: zod_types_1.zodPeerId.optional(),
+    by: invite_token_1.inviteIdentitySchema,
+    byDeviceId: zod_types_1.zodPeerId,
+})
+    .strict();
+/** Any message that travels inside an invite envelope. */
+exports.inviteMessageSchema = zod_1.z.discriminatedUnion("kind", [
+    exports.contactReplySchema,
+    exports.groupJoinRequestSchema,
+    exports.groupApprovalSchema,
+    exports.inviteDeclineSchema,
+    exports.inviteAcceptedSchema,
+]);
+/**
+ * Wire format for invite traffic over the mesh (`dataContextId: "invite"`) and the mailbox.
+ * The message is signed by the sender's user key, then boxed to the recipient's user box key,
+ * so any of the recipient's devices can open it and the relay learns only the recipient id.
+ */
+exports.inviteEnvelopeSchema = zod_1.z
+    .object({
+    v: zod_1.z.literal(1),
+    to: zod_types_1.zodPeerId,
+    box: data_box_schema_1.dataBoxSchema,
+})
+    .strict();
+/** Signs a message with the sender's user key and boxes it to the recipient's user box key. */
+function sealInviteEnvelope(message, senderKeys, recipient) {
+    const parsed = exports.inviteMessageSchema.parse(message);
+    const signed = (0, keys_1.signObjectWithSecretKey)(parsed, senderKeys.secretKey);
+    const box = (0, keys_1.boxDataWithKeys)(signed, recipient.publicBoxKey, senderKeys.secretKey);
+    return exports.inviteEnvelopeSchema.parse({ v: 1, to: recipient.userId, box });
+}
+/**
+ * Opens an envelope addressed to this user and verifies the inner signature.
+ *
+ * @throws when the box cannot be opened, the signature is invalid, or the message is malformed
+ */
+function openInviteEnvelope(envelope, recipient) {
+    const parsed = exports.inviteEnvelopeSchema.parse(envelope);
+    if (parsed.to !== recipient.userId) {
+        throw new Error("Invite envelope is addressed to a different user");
+    }
+    const signed = (0, keys_1.openBoxWithSecretKey)(parsed.box, recipient.secretKey);
+    const message = exports.inviteMessageSchema.parse((0, keys_1.openSignedObject)(signed));
+    return {
+        message,
+        senderPublicKey: signed.publicKey,
+        senderPublicBoxKey: parsed.box.fromPublicKey,
+    };
+}
+/** Returns the identity a message claims for its sender, for cross-checking against the envelope. */
+function inviteMessageSender(message) {
+    switch (message.kind) {
+        case "contact-reply":
+            return message.responder;
+        case "group-join-request":
+            return message.requester;
+        case "group-approval":
+            return message.approver;
+        case "invite-decline":
+        case "invite-accepted":
+            return message.by;
+    }
+}

package/dist/invites/invite-token.d.ts

@@ -0,0 +1,334 @@
+import { z } from "zod";
+import { GroupMemberRole } from "../data/group-member-roles";
+/** Token format version this module produces and accepts. */
+export declare const PEERS_INVITE_VERSION = 1;
+/** Canonical landing page that carries a token in its URL fragment. */
+export declare const PEERS_INVITE_URL_BASE = "https://peers.app/i";
+/** URL fragment prefix used when a token is handed to the web app directly. */
+export declare const PEERS_INVITE_APP_FRAGMENT_PREFIX = "#invite=";
+/** Default and maximum lifetimes for each invite shape. */
+export declare const INVITE_EXPIRY: {
+    readonly contactDefaultMs: number;
+    readonly profileDefaultMs: number;
+    readonly groupApproveDefaultMs: number;
+    readonly groupOpenDefaultMs: number;
+    readonly groupMaxMs: number;
+    readonly contactMaxMs: number;
+};
+/** Public identity of a party to an invite. */
+export declare const inviteIdentitySchema: z.ZodObject<{
+    userId: z.ZodEffects<z.ZodString, string, string>;
+    publicKey: z.ZodString;
+    publicBoxKey: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    publicKey: string;
+    publicBoxKey: string;
+    userId: string;
+    displayName?: string | undefined;
+}, {
+    publicKey: string;
+    publicBoxKey: string;
+    userId: string;
+    displayName?: string | undefined;
+}>;
+/** Public identity of a party to an invite. */
+export type InviteIdentity = z.infer<typeof inviteIdentitySchema>;
+/** How joiners are admitted by a group token. */
+export declare const groupInviteModeSchema: z.ZodEnum<["approve", "open"]>;
+/** How joiners are admitted by a group token. */
+export type GroupInviteMode = z.infer<typeof groupInviteModeSchema>;
+/** Group facts embedded in a group token so the joiner can preview it offline. */
+export declare const inviteGroupSchema: z.ZodObject<{
+    groupId: z.ZodEffects<z.ZodString, string, string>;
+    name: z.ZodString;
+    publicKey: z.ZodString;
+    publicBoxKey: z.ZodString;
+    role: z.ZodNativeEnum<typeof GroupMemberRole>;
+    mode: z.ZodEnum<["approve", "open"]>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    role: GroupMemberRole;
+    publicKey: string;
+    groupId: string;
+    publicBoxKey: string;
+    mode: "open" | "approve";
+}, {
+    name: string;
+    role: GroupMemberRole;
+    publicKey: string;
+    groupId: string;
+    publicBoxKey: string;
+    mode: "open" | "approve";
+}>;
+/** Group facts embedded in a group token. */
+export type InviteGroup = z.infer<typeof inviteGroupSchema>;
+/** Number of accepts a token allows; profile QRs and reusable group links are unlimited. */
+export declare const inviteUsesSchema: z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<"unlimited">]>;
+/** Unsigned contents of a PeersInvite v1 token. */
+export declare const peersInviteContentsSchema: z.ZodEffects<z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    type: z.ZodEnum<["contact", "group"]>;
+    inviter: z.ZodObject<{
+        userId: z.ZodEffects<z.ZodString, string, string>;
+        publicKey: z.ZodString;
+        publicBoxKey: z.ZodString;
+        displayName: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    }, {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    }>;
+    /** ISO 8601 instant after which the token is invalid. */
+    expiresAt: z.ZodString;
+    /** 128-bit random value; identifies the token and links replies to it. */
+    nonce: z.ZodString;
+    /** Inviter's invite epoch at issue time; a bumped epoch revokes the token. */
+    epoch: z.ZodNumber;
+    uses: z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<"unlimited">]>;
+    group: z.ZodOptional<z.ZodObject<{
+        groupId: z.ZodEffects<z.ZodString, string, string>;
+        name: z.ZodString;
+        publicKey: z.ZodString;
+        publicBoxKey: z.ZodString;
+        role: z.ZodNativeEnum<typeof GroupMemberRole>;
+        mode: z.ZodEnum<["approve", "open"]>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        role: GroupMemberRole;
+        publicKey: string;
+        groupId: string;
+        publicBoxKey: string;
+        mode: "open" | "approve";
+    }, {
+        name: string;
+        role: GroupMemberRole;
+        publicKey: string;
+        groupId: string;
+        publicBoxKey: string;
+        mode: "open" | "approve";
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    type: "group" | "contact";
+    nonce: string;
+    expiresAt: string;
+    v: 1;
+    inviter: {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    };
+    epoch: number;
+    uses: 1 | "unlimited";
+    group?: {
+        name: string;
+        role: GroupMemberRole;
+        publicKey: string;
+        groupId: string;
+        publicBoxKey: string;
+        mode: "open" | "approve";
+    } | undefined;
+}, {
+    type: "group" | "contact";
+    nonce: string;
+    expiresAt: string;
+    v: 1;
+    inviter: {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    };
+    epoch: number;
+    uses: 1 | "unlimited";
+    group?: {
+        name: string;
+        role: GroupMemberRole;
+        publicKey: string;
+        groupId: string;
+        publicBoxKey: string;
+        mode: "open" | "approve";
+    } | undefined;
+}>, {
+    type: "group" | "contact";
+    nonce: string;
+    expiresAt: string;
+    v: 1;
+    inviter: {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    };
+    epoch: number;
+    uses: 1 | "unlimited";
+    group?: {
+        name: string;
+        role: GroupMemberRole;
+        publicKey: string;
+        groupId: string;
+        publicBoxKey: string;
+        mode: "open" | "approve";
+    } | undefined;
+}, {
+    type: "group" | "contact";
+    nonce: string;
+    expiresAt: string;
+    v: 1;
+    inviter: {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    };
+    epoch: number;
+    uses: 1 | "unlimited";
+    group?: {
+        name: string;
+        role: GroupMemberRole;
+        publicKey: string;
+        groupId: string;
+        publicBoxKey: string;
+        mode: "open" | "approve";
+    } | undefined;
+}>;
+/** Unsigned contents of a PeersInvite v1 token. */
+export type PeersInviteContents = z.infer<typeof peersInviteContentsSchema>;
+/** Signed PeersInvite v1 token: contents plus the inviter's detached Ed25519 signature. */
+export declare const peersInviteSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    type: z.ZodEnum<["contact", "group"]>;
+    inviter: z.ZodObject<{
+        userId: z.ZodEffects<z.ZodString, string, string>;
+        publicKey: z.ZodString;
+        publicBoxKey: z.ZodString;
+        displayName: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    }, {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    }>;
+    expiresAt: z.ZodString;
+    nonce: z.ZodString;
+    epoch: z.ZodNumber;
+    uses: z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<"unlimited">]>;
+    group: z.ZodOptional<z.ZodObject<{
+        groupId: z.ZodEffects<z.ZodString, string, string>;
+        name: z.ZodString;
+        publicKey: z.ZodString;
+        publicBoxKey: z.ZodString;
+        role: z.ZodNativeEnum<typeof GroupMemberRole>;
+        mode: z.ZodEnum<["approve", "open"]>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        role: GroupMemberRole;
+        publicKey: string;
+        groupId: string;
+        publicBoxKey: string;
+        mode: "open" | "approve";
+    }, {
+        name: string;
+        role: GroupMemberRole;
+        publicKey: string;
+        groupId: string;
+        publicBoxKey: string;
+        mode: "open" | "approve";
+    }>>;
+    signature: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "group" | "contact";
+    nonce: string;
+    signature: string;
+    expiresAt: string;
+    v: 1;
+    inviter: {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    };
+    epoch: number;
+    uses: 1 | "unlimited";
+    group?: {
+        name: string;
+        role: GroupMemberRole;
+        publicKey: string;
+        groupId: string;
+        publicBoxKey: string;
+        mode: "open" | "approve";
+    } | undefined;
+}, {
+    type: "group" | "contact";
+    nonce: string;
+    signature: string;
+    expiresAt: string;
+    v: 1;
+    inviter: {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    };
+    epoch: number;
+    uses: 1 | "unlimited";
+    group?: {
+        name: string;
+        role: GroupMemberRole;
+        publicKey: string;
+        groupId: string;
+        publicBoxKey: string;
+        mode: "open" | "approve";
+    } | undefined;
+}>;
+/** Signed PeersInvite v1 token. */
+export type PeersInvite = z.infer<typeof peersInviteSchema>;
+/** Generates a fresh 128-bit token nonce. */
+export declare function newInviteNonce(): string;
+/** Signs token contents with the inviter's secret key. */
+export declare function createInviteToken(contents: Omit<PeersInviteContents, "v">, inviterSecretKey: string): PeersInvite;
+/** Encodes a token as unpadded base64url for URLs, QR codes, and copy/paste. */
+export declare function encodeInviteToken(token: PeersInvite): string;
+/** Options that tighten {@link parseInviteToken}. */
+export interface ParseInviteTokenOptions {
+    /** Reject tokens of any other type. */
+    expectType?: PeersInvite["type"];
+    /** Clock used for expiry; defaults to `Date.now()`. */
+    now?: number;
+    /** Skip the expiry check (e.g. to show why a token is stale). */
+    allowExpired?: boolean;
+}
+/**
+ * Parses a pasted token, invite URL, or `peers://` link and verifies its signature and expiry.
+ *
+ * @throws with a user-safe message that never echoes the input
+ */
+export declare function parseInviteToken(input: string, options?: ParseInviteTokenOptions): PeersInvite;
+/** Whether a token's expiry has passed. */
+export declare function isInviteExpired(token: Pick<PeersInvite, "expiresAt">, now?: number): boolean;
+/**
+ * Pulls the base64url token out of any of the shapes users paste: the bare token,
+ * `https://peers.app/i#<token>`, `/?app#invite=<token>`, or `peers://i#<token>`.
+ */
+export declare function extractInviteTokenText(input: string): string;
+/** Builds the shareable landing-page URL; the token travels only in the fragment. */
+export declare function inviteUrl(token: PeersInvite, base?: string): string;
+/** Builds the desktop deep link handled by the `peers://` protocol handler. */
+export declare function inviteDeepLink(token: PeersInvite): string;
+/** Clamps a requested lifetime to the allowed range for the token shape. */
+export declare function clampInviteExpiry(requestedMs: number | undefined, defaults: {
+    defaultMs: number;
+    maxMs: number;
+}): number;

package/dist/invites/invite-token.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.peersInviteSchema = exports.peersInviteContentsSchema = exports.inviteUsesSchema = exports.inviteGroupSchema = exports.groupInviteModeSchema = exports.inviteIdentitySchema = exports.INVITE_EXPIRY = exports.PEERS_INVITE_APP_FRAGMENT_PREFIX = exports.PEERS_INVITE_URL_BASE = exports.PEERS_INVITE_VERSION = void 0;
+exports.newInviteNonce = newInviteNonce;
+exports.createInviteToken = createInviteToken;
+exports.encodeInviteToken = encodeInviteToken;
+exports.parseInviteToken = parseInviteToken;
+exports.isInviteExpired = isInviteExpired;
+exports.extractInviteTokenText = extractInviteTokenText;
+exports.inviteUrl = inviteUrl;
+exports.inviteDeepLink = inviteDeepLink;
+exports.clampInviteExpiry = clampInviteExpiry;
+const zod_1 = require("zod");
+const group_member_roles_1 = require("../data/group-member-roles");
+const keys_1 = require("../keys");
+const zod_types_1 = require("../types/zod-types");
+const base64UrlSchema = zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/);
+/** Token format version this module produces and accepts. */
+exports.PEERS_INVITE_VERSION = 1;
+/** Canonical landing page that carries a token in its URL fragment. */
+exports.PEERS_INVITE_URL_BASE = "https://peers.app/i";
+/** URL fragment prefix used when a token is handed to the web app directly. */
+exports.PEERS_INVITE_APP_FRAGMENT_PREFIX = "#invite=";
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Default and maximum lifetimes for each invite shape. */
+exports.INVITE_EXPIRY = {
+    contactDefaultMs: 7 * DAY_MS,
+    profileDefaultMs: 365 * DAY_MS,
+    groupApproveDefaultMs: 7 * DAY_MS,
+    groupOpenDefaultMs: DAY_MS,
+    groupMaxMs: 30 * DAY_MS,
+    contactMaxMs: 365 * DAY_MS,
+};
+/** Public identity of a party to an invite. */
+exports.inviteIdentitySchema = zod_1.z
+    .object({
+    userId: zod_types_1.zodPeerId,
+    publicKey: base64UrlSchema.length(43),
+    publicBoxKey: base64UrlSchema.length(43),
+    displayName: zod_1.z.string().max(100).optional(),
+})
+    .strict();
+/** How joiners are admitted by a group token. */
+exports.groupInviteModeSchema = zod_1.z.enum(["approve", "open"]);
+/** Group facts embedded in a group token so the joiner can preview it offline. */
+exports.inviteGroupSchema = zod_1.z
+    .object({
+    groupId: zod_types_1.zodPeerId,
+    name: zod_1.z.string().max(200),
+    publicKey: base64UrlSchema.length(43),
+    publicBoxKey: base64UrlSchema.length(43),
+    role: zod_1.z.nativeEnum(group_member_roles_1.GroupMemberRole),
+    mode: exports.groupInviteModeSchema,
+})
+    .strict();
+/** Number of accepts a token allows; profile QRs and reusable group links are unlimited. */
+exports.inviteUsesSchema = zod_1.z.union([zod_1.z.literal(1), zod_1.z.literal("unlimited")]);
+/** Unsigned contents of a PeersInvite v1 token. */
+exports.peersInviteContentsSchema = zod_1.z
+    .object({
+    v: zod_1.z.literal(exports.PEERS_INVITE_VERSION),
+    type: zod_1.z.enum(["contact", "group"]),
+    inviter: exports.inviteIdentitySchema,
+    /** ISO 8601 instant after which the token is invalid. */
+    expiresAt: zod_1.z.string().datetime(),
+    /** 128-bit random value; identifies the token and links replies to it. */
+    nonce: base64UrlSchema.length(22),
+    /** Inviter's invite epoch at issue time; a bumped epoch revokes the token. */
+    epoch: zod_1.z.number().int().min(0),
+    uses: exports.inviteUsesSchema,
+    group: exports.inviteGroupSchema.optional(),
+})
+    .strict()
+    .refine((value) => (value.type === "group") === (value.group !== undefined), {
+    message: "Group tokens must carry group facts and contact tokens must not",
+});
+/** Signed PeersInvite v1 token: contents plus the inviter's detached Ed25519 signature. */
+exports.peersInviteSchema = zod_1.z
+    .object({
+    v: zod_1.z.literal(exports.PEERS_INVITE_VERSION),
+    type: zod_1.z.enum(["contact", "group"]),
+    inviter: exports.inviteIdentitySchema,
+    expiresAt: zod_1.z.string().datetime(),
+    nonce: base64UrlSchema.length(22),
+    epoch: zod_1.z.number().int().min(0),
+    uses: exports.inviteUsesSchema,
+    group: exports.inviteGroupSchema.optional(),
+    signature: base64UrlSchema.length(86),
+})
+    .strict();
+/** Generates a fresh 128-bit token nonce. */
+function newInviteNonce() {
+    return (0, keys_1.newToken)(16);
+}
+/** Signs token contents with the inviter's secret key. */
+function createInviteToken(contents, inviterSecretKey) {
+    const parsed = exports.peersInviteContentsSchema.parse({ v: exports.PEERS_INVITE_VERSION, ...contents });
+    const signed = (0, keys_1.signObjectWithSecretKey)(parsed, inviterSecretKey);
+    if (signed.publicKey !== parsed.inviter.publicKey) {
+        throw new Error("Invite must be signed by the inviter's own key");
+    }
+    return exports.peersInviteSchema.parse({ ...parsed, signature: signed.signature });
+}
+/** Encodes a token as unpadded base64url for URLs, QR codes, and copy/paste. */
+function encodeInviteToken(token) {
+    return (0, keys_1.encodeBase64)(new TextEncoder().encode(JSON.stringify(exports.peersInviteSchema.parse(token))));
+}
+/**
+ * Parses a pasted token, invite URL, or `peers://` link and verifies its signature and expiry.
+ *
+ * @throws with a user-safe message that never echoes the input
+ */
+function parseInviteToken(input, options = {}) {
+    const encoded = extractInviteTokenText(input);
+    let token;
+    try {
+        const json = new TextDecoder().decode((0, keys_1.decodeBase64)(encoded));
+        token = exports.peersInviteSchema.parse(JSON.parse(json));
+    }
+    catch {
+        throw new Error("Invite is not a valid Peers invite");
+    }
+    const { signature, ...contents } = token;
+    try {
+        (0, keys_1.openSignedObject)({
+            contents: exports.peersInviteContentsSchema.parse(contents),
+            signature,
+            publicKey: token.inviter.publicKey,
+        });
+    }
+    catch {
+        throw new Error("Invite signature is not valid");
+    }
+    if (options.expectType && token.type !== options.expectType) {
+        throw new Error(`Expected a ${options.expectType} invite`);
+    }
+    if (!options.allowExpired && isInviteExpired(token, options.now)) {
+        throw new Error("Invite has expired");
+    }
+    return token;
+}
+/** Whether a token's expiry has passed. */
+function isInviteExpired(token, now = Date.now()) {
+    return Date.parse(token.expiresAt) <= now;
+}
+/**
+ * Pulls the base64url token out of any of the shapes users paste: the bare token,
+ * `https://peers.app/i#<token>`, `/?app#invite=<token>`, or `peers://i#<token>`.
+ */
+function extractInviteTokenText(input) {
+    const trimmed = input.trim();
+    const hashIndex = trimmed.indexOf("#");
+    let candidate = hashIndex >= 0 ? trimmed.slice(hashIndex + 1) : trimmed;
+    if (candidate.startsWith(exports.PEERS_INVITE_APP_FRAGMENT_PREFIX.slice(1))) {
+        candidate = candidate.slice(exports.PEERS_INVITE_APP_FRAGMENT_PREFIX.length - 1);
+    }
+    candidate = candidate.split(/[?&\s]/)[0];
+    if (!/^[A-Za-z0-9_-]{16,}$/.test(candidate)) {
+        throw new Error("Invite is not a valid Peers invite");
+    }
+    return candidate;
+}
+/** Builds the shareable landing-page URL; the token travels only in the fragment. */
+function inviteUrl(token, base = exports.PEERS_INVITE_URL_BASE) {
+    return `${base}#${encodeInviteToken(token)}`;
+}
+/** Builds the desktop deep link handled by the `peers://` protocol handler. */
+function inviteDeepLink(token) {
+    return `peers://i#${encodeInviteToken(token)}`;
+}
+/** Clamps a requested lifetime to the allowed range for the token shape. */
+function clampInviteExpiry(requestedMs, defaults) {
+    const value = requestedMs ?? defaults.defaultMs;
+    if (!Number.isFinite(value) || value <= 0) {
+        return defaults.defaultMs;
+    }
+    return Math.min(value, defaults.maxMs);
+}

package/dist/invites/invite-token.test.d.ts

@@ -0,0 +1 @@
+export {};