@irbisadm/simple-sdp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Igor Sheko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.mjs

@@ -0,0 +1 @@
+const e=(e,t)=>e.replace(`${t}=`,"").split(" "),t=/^\d+$/,r=e=>{if(!t.test(e))throw new Error(`"${e}" is not an integer.`);return parseInt(e)},s=e=>{const t={d:86400,h:86400,m:60,s:1};if(Object.keys(t).includes(e.slice(-1))){const s=e.slice(-1),n=e.slice(0,e.length-1),a=r(n);return t[s]*a}return r(e)},n=e=>e.split("/").map((e=>parseInt(e))),a=t=>{const r=e(t,"m");switch(r[0]){case"audio":return(e=>{const t={type:e[0],ports:n(e[1]),proto:e[2]};if(e.length>3){t.fmtp=[];for(let r=3;r<e.length;r++)t.fmtp.push(parseInt(e[r]))}return t})(r);case"application":return(e=>({type:"application",ports:n(e[1]),proto:e[2],description:e[3]}))(r);default:return(e=>{const t={type:e[0],ports:n(e[1]),proto:e[2]};if(e.length>3){t.fmtp=[];for(let r=3;r<e.length;r++)t.fmtp.push(e[r])}return t})(r)}},i=e=>{const t=e.replace("k=",""),[s,n]=t.split(":");return{bwtype:s,bandwidth:r(n)}},o=t=>{const r=e(t,"c");return{netType:"IN"===r[0]?"IN":void 0,addrType:["IP4","IP6"].includes(r[1])?r[1]:void 0,connectionAddress:r[2]}},c=(e,t,r)=>{e.ice||(e.ice={ufrag:"",pwd:"",options:[]}),e.ice[t]=r},p=(e,t,r)=>{e.dtls||(e.dtls={algorithm:"",fingerprint:"",setup:"actpass"}),e.dtls[t]=r},l=(e,t)=>{e.attributes||(e.attributes={});const r=t.replace("a=",""),[s,...n]=r.split(":"),a=n.join(":");switch(s){case"mid":e.mid=a;break;case"ice-ufrag":c(e,"ufrag",a);break;case"ice-pwd":c(e,"pwd",a);break;case"ice-options":c(e,"options",a.split(" "));break;case"fingerprint":{const[t,r]=a.split(" ");p(e,"algorithm",t),p(e,"fingerprint",r);break}case"setup":p(e,"setup",a);break;case"sendrecv":e.direction=s;break;default:if(e.attributes[s]){Array.isArray(e.attributes[s])||(e.attributes[s]=[e.attributes[s]]),e.attributes[s].push(a);break}e.attributes[s]=0===n.length||a}return e},u=t=>{const r=t.split("\r\n"),n={};let c=null;return r.forEach(((t,p)=>{if(0!==t.length){if("="!==t[1])throw new Error(`Invalid line structure in line "${t}"`);switch(t[0]){case"v":n.protocolVersion=(e=>parseInt(e.replace("v=","")))(t);break;case"o":n.origin=(t=>{const r=e(t,"o"),s=parseInt(r[2]),n="IN"===r[3]?"IN":void 0,a=["IP4","IP6"].includes(r[4])?r[4]:void 0;return{username:r[0],sessId:r[1],sessVersion:s,netType:n,addrType:a,unicastAddress:r[5]}})(t);break;case"s":n.sessionName=(e=>e.replace("s=",""))(t);break;case"t":n.timing||(n.timing=[]),n.timing.push((t=>{const r=e(t,"t"),s=parseInt(r[0]),n=isNaN(s)?0:s,a=parseInt(r[1]);return{startTime:n,stopTime:isNaN(a)?0:a}})(t));break;case"r":n.repeat||(n.repeat=[]),n.repeat.push((t=>{const r=e(t,"r"),n={repeatInterval:s(r[0]),activeDuration:s(r[0])};if(r.length>3){n.offsets=[];for(let e=2;e<r.length;e++)n.offsets.push(s(r[e]))}return n})(t));break;case"i":n.sessionInformation=(e=>e.replace("i=",""))(t);break;case"u":n.sessionInformation=(e=>e.replace("u=",""))(t);break;case"e":n.emailAddress=(e=>e.replace("e=",""))(t);break;case"p":n.phoneNumber=(e=>e.replace("p=",""))(t);break;case"k":n.encryptionKeys||(n.encryptionKeys=[]),n.encryptionKeys.push((e=>{const t=e.replace("k=",""),[r,s]=t.split(":");if(!["clear","base64","uri","prompt"].includes(r))throw new Error(`Encryption method "${r}" is not supported by RFC-4566`);return{method:r,encryptionKey:s}})(t));break;case"m":const r=a(t);c=r,n.media||(n.media=[]),n.media.push(r);break;case"b":c?c.bandwidthInformation=i(t):n.bandwidthInformation=i(t);break;case"c":c?c.connectionInformation=o(t):n.connectionInformation=o(t);break;case"a":l(c||n,t);break;default:throw Error(`Unknown line type "${t[0]}"`)}}else if(p!==r.length-1)throw new Error(`Empty line at "${p}" after ${r[p-1]}`)})),n},d={parse:u,isValid:(e,t=!1)=>{try{return u(e),!0}catch(e){return t&&console.error(e),!1}}},b="0.1.0";export{d as sdpReader,b as version};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@irbisadm/simple-sdp",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "WebRTC SDP parser and validator influenced by pjsip library.",
+  "author": {
+    "email": "i@irbisadm.dev",
+    "name": "Igor Sheko",
+    "url": "https://www.linkedin.com/in/irbisadm/"
+  },
+  "private": false,
+  "repository": "https://github.com/irbisadm/simple-sdp",
+  "bugs": "https://github.com/irbisadm/simple-sdp/issues",
+  "module": "./dist/index.mjs",
+  "main": "./dist/index.mjs",
+  "types": "./types/index.d.ts",
+  "files": [
+    "./dist/index.mjs",
+    "./types/index.d.ts",
+    "./readme.md"
+  ],
+  "devDependencies": {
+    "@rollup/plugin-replace": "^5.0.2",
+    "@rollup/plugin-terser": "^0.4.0",
+    "@rollup/plugin-typescript": "^11.0.0",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^18.14.0",
+    "jest": "^29.5.0",
+    "rollup": "^3.17.1",
+    "rollup-plugin-dts": "^5.2.0",
+    "ts-jest": "^29.0.5",
+    "tslib": "^2.5.0",
+    "typescript": "^5.0.2"
+  },
+  "engines": {
+    "node": ">=17.0.0"
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "test": "jest"
+  }
+}

package/readme.md

@@ -0,0 +1,23 @@
+![license MIT](https://badgen.net/npm/license/@irbisadm/simple-sdp)
+![license MIT](https://badgen.net/npm/v/@irbisadm/simple-sdp)
+![license MIT](https://badgen.net/npm/types/@irbisadm/simple-sdp)
+![license MIT](https://badgen.net/bundlephobia/minzip/@irbisadm/simple-sdp)
+![license MIT](https://badgen.net/bundlephobia/dependency-count/@irbisadm/simple-sdp)
+![license MIT](https://badgen.net/bundlephobia/tree-shaking/@irbisadm/simple-sdp)
+# Simple SDP tools
+This project is a TypeScript library that provides a comprehensive set of tools for working with Session Description Protocol (SDP) messages in WebRTC applications. SDP is a text-based format that describes the multimedia communication sessions between peers. 
+With this library, you can:
+- Parse and generate SDP messages from and to TypeScript objects
+- Manipulate SDP data by adding, removing, or modifying media streams, codecs, candidates, and other attributes
+- Validate SDP messages according to the [RFC 4566](https://www.rfc-editor.org/rfc/rfc8866) specification and WebRTC best practices
+- Track and verify the SDP history for a single PeerConnection instance
+
+This project aims to help WebRTC beginners learn the SDP format and its components, as well as provide a clear and easy-to-use TypeScript API for advanced users. This project was inspired by the [pjsip](https://github.com/pjsip/pjproject) library written in C++.
+
+You can use the library with Node.js as well in any modern web browser.
+
+## SIP disclaimer
+Probably this library can be used for parsing and creating SDP for SIP. 
+I can see a theoretical problems here because some SIP devices are complained only with older SDP RFC: [RFC 4566](https://www.rfc-editor.org/rfc/rfc4566.html) or [RFC 2327](https://www.rfc-editor.org/rfc/rfc2327).
+
+I'm not an expert in SIP and have no test environment to check compatibility with that standards. If you can help with tests or expertise with SIP, please send me a message to [i@irbisadm.dev](mailto:i@irbisadm.dev)

package/types/index.d.ts

@@ -0,0 +1,284 @@
+interface SdpCommonAttributes {
+    attributes?: Record<string, SdpAttribute>;
+    ice?: SdpIceAttributes;
+    dtls?: SdpDtlsAttribute;
+}
+interface Sdp extends SdpCommonAttributes {
+    protocolVersion?: number;
+    /**
+     * The "o=" field gives the originator of the session (her username and the address of the user's host) plus a session
+     * identifier and version number:
+     */
+    origin?: SdpOrigin;
+    /**
+     * The "s=" field is the textual session name. There MUST be one and only one "s=" field per session description. The
+     * "s=" field MUST NOT be empty and SHOULD contain ISO 10646 characters (but see also the "a=charset" attribute).
+     * If a session has no meaningful name, the value "s= " SHOULD be used (i.e., a single space as the session name).
+     */
+    sessionName?: string;
+    /**
+     *
+     * The "i=" field provides textual information about the session. There MUST be at most one session-level "i="
+     * field per session description, and at most one "i=" field per media. If the "a=charset" attribute is present,
+     * it specifies the character set used in the "i=" field. If the "a=charset" attribute is not present, the "i="
+     * field MUST contain ISO 10646 characters in UTF-8 encoding.
+     * A single "i=" field MAY also be used for each media definition. In media definitions, "i=" fields are
+     * primarily intended for labelling media streams.  As such, they are most likely to be useful when a single
+     * session has more than one distinct media stream of the same media type.  An example would be two different
+     * whiteboards, one for slides and one for feedback and questions. The "i=" field is intended to provide a
+     * free-form human-readable description of the session or the purpose of a media stream. It is not suitable
+     * for parsing by automata.
+     */
+    sessionInformation?: string;
+    /**
+     * A URI is a Uniform Resource Identifier as used by WWW clients. The URI should be a pointer to additional
+     * information about the session. This field is OPTIONAL, but if it is present it MUST be specified before the
+     * first media field. No more than one URI field is allowed per session description.
+     */
+    uri?: string;
+    emailAddress?: string;
+    phoneNumber?: string;
+    encryptionKeys?: SdpEncryptionKey[];
+    /**
+     *  The "t=" lines specify the start and stop times for a session. Multiple "t=" lines MAY be used if a session is
+     *  active at multiple irregularly spaced times; each additional "t=" line specifies an additional period of time for
+     *  which the session will be active. If the session is active at regular times, an "r=" line (see below) should be
+     *  used in addition to, and following, a "t=" line -- in which case the "t=" line specifies the start and stop times
+     *  of the repeat sequence.
+     */
+    timing?: SdpTiming[];
+    /**
+     * "r=" fields specify repeat times for a session. For example, if a session is active at 10am on Monday and 11am on
+     * Tuesday for one hour each week for three months, then the <start-time> in the corresponding "t=" field would be the
+     * NTP representation of 10am on the first Monday, the <repeat interval> would be 1 week, the <active duration> would
+     * be 1 hour, and the offsets would be zero and 25 hours. The corresponding "t=" field stop time would be the NTP
+     * representation of the end of the last session three months later.
+     */
+    repeat?: SdpRepeatTimes[];
+    media?: SdpMediaSection[];
+    bandwidthInformation?: SdpBandwidthInformation;
+    connectionInformation?: SdpConnectionInformation;
+}
+/**
+ * The "o=" field gives the originator of the session (her username and the address of the user's host) plus a session
+ * identifier and version number:
+ */
+interface SdpOrigin {
+    /**
+     * <username> is the user's login on the originating host, or it is "-" if the originating host does not support
+     * the concept of user IDs. The <username> MUST NOT contain spaces.
+     */
+    username?: string;
+    /**
+     * <sess-id> is a numeric string such that the tuple of <username>, <sess-id>, <nettype>, <addrtype>, and
+     * <unicast-address> forms a globally unique identifier for the session.  The method of <sess-id> allocation is up
+     * to the creating tool, but it has been suggested that a Network Time Protocol (NTP) format timestamp be used to
+     * ensure uniqueness
+     */
+    sessId?: string;
+    /**
+     * <sess-version> is a version number for this session description. Its usage is up to the creating tool, so long as
+     * <sess-version> is increased when a modification is made to the session data. Again, it is RECOMMENDED that an NTP
+     * format timestamp is used.
+     */
+    sessVersion?: number;
+    /**
+     * <nettype> is a text string giving the type of network. Initially "IN" is defined to have the meaning "Internet",
+     * but other values MAY be registered in the future.
+     */
+    netType?: 'IN';
+    /**
+     * <addrtype> is a text string giving the type of the address that follows. Initially "IP4" and "IP6" are defined,
+     * but other values MAY be registered in the future
+     */
+    addrType?: 'IP4' | 'IP6';
+    /**
+     * <unicast-address> is the address of the machine from which the session was created. For an address type of IP4,
+     * this is either the fully qualified domain name of the machine or the dotted-decimal representation of the
+     * IP version 4 address of the machine. For an address type of IP6, this is either the fully qualified domain name of
+     * the machine or the compressed textual representation of the IP version 6 address of the machine. For both IP4
+     * and IP6, the fully qualified domain name is the form that SHOULD be given unless this is unavailable, in which case
+     * the globally unique address MAY be substituted. A local IP address MUST NOT be used in any context where the SDP
+     * description might leave the scope in which the address is meaningful (for example, a local address MUST NOT be
+     * included in an application-level referral that might leave the scope).
+     */
+    unicastAddress: string;
+}
+/**
+ *  The "t=" lines specify the start and stop times for a session. Multiple "t=" lines MAY be used if a session is
+ *  active at multiple irregularly spaced times; each additional "t=" line specifies an additional period of time for
+ *  which the session will be active. If the session is active at regular times, an "r=" line (see below) should be
+ *  used in addition to, and following, a "t=" line -- in which case the "t=" line specifies the start and stop times
+ *  of the repeat sequence.
+ */
+interface SdpTiming {
+    startTime: number;
+    stopTime: number;
+}
+/**
+ * "r=" fields specify repeat times for a session. For example, if a session is active at 10am on Monday and 11am on
+ * Tuesday for one hour each week for three months, then the <start-time> in the corresponding "t=" field would be the
+ * NTP representation of 10am on the first Monday, the <repeat interval> would be 1 week, the <active duration> would
+ * be 1 hour, and the offsets would be zero and 25 hours. The corresponding "t=" field stop time would be the NTP
+ * representation of the end of the last session three months later.
+ */
+interface SdpRepeatTimes {
+    repeatInterval: number;
+    activeDuration: number;
+    offsets?: number[];
+}
+/**
+ * If transported over a secure and trusted channel, the Session Description Protocol MAY be used to convey encryption
+ * keys. A simple mechanism for key exchange is provided by the key field ("k="), although this is primarily
+ * supported for compatibility with older implementations and its use is NOT RECOMMENDED. Work is in progress to define
+ * new key exchange mechanisms for use with SDP [27] [28], and it is expected that new applications will use
+ * those mechanisms.
+ *
+ * A key field is permitted before the first media entry (in which case it applies to all media in the session), or
+ * for each media entry as required. The format of keys and their usage are outside the scope of this document, and
+ * the key field provides no way to indicate the encryption algorithm to be used, key type, or other information about
+ * the key: this is assumed to be provided by the higher-level protocol using SDP. If there is a need to convey this
+ * information within SDP, the extensions mentioned previously SHOULD be used. Many security protocols require two
+ * keys: one for confidentiality, another for integrity. This specification does not support transfer of two keys.
+ */
+interface SdpEncryptionKey {
+    /**
+     * The method indicates the mechanism to be used to obtain a usable key by external means, or from the encoded
+     * encryption key given. The following methods are defined:
+     *
+     * clear
+     *   The encryption key is included untransformed in this key field. This method MUST NOT be used unless it can be
+     *   guaranteed that the SDP is conveyed over a secure channel. The encryption key is interpreted as text according
+     *   to the charset attribute; use the "k=base64:" method to convey characters that are otherwise prohibited in SDP.
+     *
+     * base64
+     *   The encryption key is included in this key field but has been base64 encoded because it includes characters
+     *   that are prohibited in SDP. This method MUST NOT be used unless it can be guaranteed that the SDP is
+     *   conveyed over a secure channel.
+     *
+     * uri
+     *   A Uniform Resource Identifier is included in the key field. The URI refers to the data containing the key,
+     *   and may require additional authentication before the key can be returned. When a request is made to the given
+     *   URI, the reply should specify the encoding for the key.  The URI is often an Secure Socket Layer/Transport
+     *   Layer Security (SSL/TLS)-protected HTTP URI ("https:"), although this is not required.
+     *
+     * prompt
+     *  No key is included in this SDP description, but the session or media stream referred to by this key field
+     *  is encrypted. The user should be prompted for the key when attempting to join the session, and this
+     *  user-supplied key should then be used to decrypt the media streams.  The use of user-specified keys is
+     *  NOT RECOMMENDED, since such keys tend to have weak security properties.
+     */
+    method: 'clear' | 'base64' | 'uri' | 'prompt';
+    encryptionKey?: string;
+}
+/**
+ * The OPTIONAL "b=" line (bandwidth-field) denotes the proposed bandwidth to be used by the session or media
+ * description. The <bwtype> is an alphanumeric modifier that provides the meaning of the <bandwidth> number. Two
+ * values are defined in this specification, but other values MAY be registered in the future
+ * (see Section 8 and [RFC3556], [RFC3890]):
+ */
+interface SdpBandwidthInformation {
+    /**
+     * CT
+     *   If the bandwidth of a session is different from the bandwidth implicit from the scope, a "b=CT:" line SHOULD
+     *   be supplied for the session giving the proposed upper limit to the bandwidth used
+     *   (the "conference total" bandwidth). Similarly, if the bandwidth of bundled media streams [RFC8843] in
+     *   an "m=" line is different from the implicit value from the scope, a "b=CT:" line SHOULD be supplied in the
+     *   media level. The primary purpose of this is to give an approximate idea as to whether two or more sessions
+     *   (or bundled media streams) can coexist simultaneously. Note that a "b=CT:" line gives a total bandwidth figure
+     *   for all the media at all endpoints.
+     *
+     * The Mux Category for "b=CT:" is NORMAL. This is discussed in [RFC8859].
+     *
+     * AS
+     *  The bandwidth is interpreted to be application specific (it will be the application's concept
+     *  of maximum bandwidth). Normally, this will coincide with what is set on the application's "maximum bandwidth"
+     *  control if applicable. For RTP-based applications, the "b=AS:" line gives the RTP "session bandwidth" as defined
+     *  in Section 6.2 of [RFC3550]. Note that a "b=AS:" line gives a bandwidth figure for a single media at
+     *  a single endpoint, although there may be many endpoints sending simultaneously.
+     *
+     * The Mux Category for "b=AS:" is SUM. This is discussed in [RFC8859].
+     *
+     * [RFC4566] defined an "X-" prefix for <bwtype> names. This was intended for experimental purposes only.
+     * Use of the "X-" prefix is NOT RECOMMENDED. Instead new (non "X-" prefix) <bwtype> names SHOULD be defined,
+     * and then MUST be registered with IANA in the standard namespace. SDP parsers MUST ignore bandwidth-fields with
+     * unknown <bwtype> names. The <bwtype> names MUST be alphanumeric and, although no length limit is given,
+     * it is recommended that they be short.
+     */
+    bwtype: string;
+    /**
+     * The <bandwidth> is interpreted as kilobits per second by default (including the transport and network-layer,
+     * but not the link-layer, overhead). The definition of a new <bwtype> modifier MAY specify that the bandwidth is
+     * to be interpreted in some alternative unit (the "CT" and "AS" modifiers defined in this memo use the default
+     * units).
+     */
+    bandwidth: number;
+}
+/**
+ * The "c=" line (connection-field) contains information necessary to establish a network connection.
+ * A session description MUST contain either at least one "c=" line in each media description or a single "c=" line
+ * at the session level. It MAY contain a single session-level "c=" line and additional media-level "c=" line(s)
+ * per-media-description, in which case the media-level values override the session-level settings for the
+ * respective media.
+ */
+interface SdpConnectionInformation {
+    /**
+     * <nettype> is a text string giving the type of network. Initially "IN" is defined to have the meaning "Internet",
+     * but other values MAY be registered in the future.
+     */
+    netType?: 'IN';
+    /**
+     * <addrtype> is a text string giving the type of the address that follows. Initially "IP4" and "IP6" are defined,
+     * but other values MAY be registered in the future
+     */
+    addrType?: 'IP4' | 'IP6';
+    /**
+     * <base multicast address>[/<ttl>]/<number of addresses>
+     */
+    connectionAddress: string;
+}
+interface SdpBaseMediaSection extends SdpCommonAttributes {
+    mid?: string;
+    direction?: 'sendrecv' | 'sendonly' | 'recvonly' | 'inactive';
+    ports: number[];
+    proto: string;
+    bandwidthInformation?: SdpBandwidthInformation;
+    connectionInformation?: SdpConnectionInformation;
+}
+interface SdpAVMediaSection extends SdpBaseMediaSection {
+    type: 'audio' | 'video';
+    fmtp?: number[];
+}
+interface SdpAppMediaSection extends SdpBaseMediaSection {
+    type: 'application';
+    description?: string;
+}
+interface SdpOtherMediaSection extends SdpBaseMediaSection {
+    type: 'text' | 'message' | string;
+    fmtp?: string[];
+}
+type SdpMediaSection = SdpAVMediaSection | SdpAppMediaSection | SdpOtherMediaSection;
+type SdpAttribute = string | boolean | string[];
+interface SdpIceAttributes {
+    ufrag: string;
+    pwd: string;
+    options: string[];
+}
+interface SdpDtlsAttribute {
+    algorithm: string;
+    fingerprint: string;
+    setup: 'active' | 'passive' | 'actpass';
+}
+interface SdpPair {
+    offer: Sdp;
+    answer: Sdp;
+}
+
+declare const sdpReader: {
+    parse: (sdp: string) => Sdp;
+    isValid: (sdp: string, writeLog?: boolean) => boolean;
+};
+
+declare const version = "0.1.0";
+
+export { Sdp, SdpEncryptionKey, SdpMediaSection, SdpOrigin, SdpPair, SdpRepeatTimes, SdpTiming, sdpReader, version };