Web Clipper is now available (BETA feature)

The authentication is not a little topic. A least if the port was just opened for the 127.0.0.1 that will restrict its access.

There are use-cases where a remote clipping server might be very useful. I believe this should be an option. However, I agree that tighter security will become relevant in the future.

Currently, the only info which is retrievable are the notebook names and their ids. At worst someone could mount a DOS attack by creating notes.

Yes we are all ok with the feature and the consequence

Ok indeed, I missed that it was opened outside of localhost.

1 Like

Really cool! Thank you so much. Mac OSX & Firefox working fine.

One possible option might be to use e.g. an AES cipher to encrypt the communication (which could then continue working over HTTPS). You would need to pre-share a key, but that could be well automated, I think.

It could then work like this:

  1. the user installs the web clipper extension and clicks 'connect to Joplin'
  2. Joplin displays a popup, something to the effect of 'attempted connection to Web Clipper endpoint, do you want to allow it?'
  3. The user clicks 'yes'. A random encryption key is generated (unique per extension instance) and stored in both Joplin and the Clipper extension.

Then when using:

  1. Endpoint only accepts encrypted connections. When a connection is made, Joplin tries the saved passwords to decrypt the contents; if it succeeds, good, it's from an pre-approved connection. If it fails, discard the message entirely.

I think there are benefits to an approach such as this one: there is some action the user needs to take, but it's basically just two clicks. And any specific key can be revoked (and thus the access channel blocked) if some foul play in suspected.
One obvious flaw is the key sharing: if some network logger were present in the instance of the first (and only) key transmit, or if it could later be dug out from the filesystem, everything is compromised. But I do think this is negligible (i.e. I'd risk it with no care) and the other attack vectors probably are much more probable. (i.e. if you already have a keylogger on your PC, you have far bigger problems than too many spam notes in Joplin; however, you might not want to expose Joplin to port scans and spam at a later time, which is the more likely scenario, anyway.)

Disclaimer: this is just an idea off the top of my head and I'm no security expert. Maybe it's dumb and I'm dumb for thinking it. :sweat_smile::woman_shrugging::smile:

1 Like

Yes that would indeed work. There's still an extra step but there's probably no way around this.

Works well on osx 10.12.5 + chrome. Amazing!

Any chance to have this feature also available on mobile phones (Android)? Don’t see a way to install plug-ins in my mobile chrome. Something like “share with Joplin”.

No as the web clipper needs a service in the background, which wouldn't work on mobile. But a way to share with the app is planned.

3 Likes

Hi, I’m looking for the web clipper Rest API docs. Exciting to see this addition!

there were some posts right here

1 Like

The Joplin Web Clipper API is now more consistent and documented below :smiley:

https://joplin.cozic.net/clipper/

You can expect it to remain stable from now on. More end points or properties might be supported later on but what's there shouldn't change.


Using the Web Clipper service

The Web Clipper service can be used to create notes from any other application. It exposes a REST API with a number of methods to list folders and to create notes or attach images.

In order to use it, you'll first need to find on which port the service is running. To do so, open the Web Clipper Option in Joplin and if the service is running it should tell you on which port. Normally it runs on port 41184. If you want to find it programmatically, you may follow this kind of algorithm:

let port = null;
for (let portToTest = 41184; portToTest <= 41194; portToTest++) {
    const result = pingPort(portToTest); // Call GET /ping
    if (result == 'JoplinClipperServer') {
        port = portToTest; // Found the port
        break;
    }
}

start from 41184, then ping it (using the /ping method below)

The following methods are available:

GET /ping

Tells whether the service is active or not. It should return "JoplinClipperServer" if it works.

Example: curl http://127.0.0.1:41184/ping

GET /folders

Returns the list of notebooks (called "folders" internally) as a tree. The sub-notebooks of a notebook, if any, are under the children key.

Example: curl http://127.0.0.1:41184/folders

POST /notes

Creates a new note. You can either specify the note body as Markdown by setting the body parameter, or in HTML by setting the body_html. All parameter are optional.

Parameters:

Key Description
title Note title
body Note body, in Markdown
body_html Note body, in HTML format
source_url The URL the note comes from
parent_id The notebook (ID) to move the note to
base_url If body_html is provided and contains relative URLs, provide the base_url parameter too so that all the URLs can be converted to absolute ones. The base URL is basically where the HTML was fetched from, minus the query (everything after the '?'). For example if the original page was https://stackoverflow.com/search?q=%5Bjava%5D+test, the base URL is https://stackoverflow.com/search.
image_data_url An image to attach to the note, in Data URL format.
crop_rect If an image is provided, you can also specify an optional rectangle that will be used to crop the image. In format { x: x, y: y, width: width, height: height }

Examples:

  • Create a note from some Markdown text

curl --data '{ "title": "My note", "body": "Some note in **Markdown**"}' http://127.0.0.1:41184/notes

  • Create a note from some HTML

curl --data '{ "title": "My note", "body_html": "Some note in <b>HTML</b>"}' http://127.0.0.1:41184/notes

  • Create a note and attach an image to it:

curl --data '{ "title": "Image test", "body": "Here is Joplin icon:", "image_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAANZJREFUeNoAyAA3/wFwtO3K6gUB/vz2+Prw9fj/+/r+/wBZKAAExOgF4/MC9ff+MRH6Ui4E+/0Bqc/zutj6AgT+/Pz7+vv7++nu82c4DlMqCvLs8goA/gL8/fz09fb59vXa6vzZ6vjT5fbn6voD/fwC8vX4UiT9Zi//APHyAP8ACgUBAPv5APz7BPj2+DIaC2o3E+3o6ywaC5fT6gD6/QD9/QEVf9kD+/dcLQgJA/7v8vqfwOf18wA1IAIEVycAyt//v9XvAPv7APz8LhoIAPz9Ri4OAgwARgx4W/6fVeEAAAAASUVORK5CYII="}' http://127.0.0.1:41184/notes

1 Like

nothing for “author” ?

I could add it. While I'm at it, are there other properties you might need?

i dont see anything else .
thanks.

Done in Clipper: Support 'author' property · laurent22/joplin@424c8a2 · GitHub

2 Likes

i'm ready to use it :slight_smile:

Is any work being done on adding the source URL of clipped note as a clickable link in the desktop version? I know it’s availble as saved metadata as a note, but not available in the desktop application.

1 Like

it’s planed

1 Like