scratch-api-unofficial-docs
scratch-api-unofficial-docs copied to clipboard
towerofnix
Log in with username and password?
Logging into the Scratch API from a third-party site is fully possible, and I have successfully implemented it in Itchy (the Scratch app I'm developing). Would the /etc section of this repository be a good place to document that?
Huh, that really doesn't seem like it should be possible. I've always assumed CORS policies would prevent you from making requests like that (or receiving any useful data back). I might be misunderstanding you, though - is your app a web app (meaning it'd be subject to browser security measures, like CORS), or is it a mobile/desktop app, which generally have free reign to make whatever requests they'd like?
Assuming it's the latter, yes, /etc would be the place to share documentation!
If you're curious, I made a write-up on the subject a couple years ago, though it still hasn't found a home beyond this gist: https://gist.github.com/towerofnix/cd5c0771446dc0ba81355fccc70ed1ea — I wouldn't expect you to follow its particular format or anything, but perhaps it'd offer some inspiration! I'd definitely be interested in your own writings. :)
@RedGuy12 Yeah, that's a place where access to the API is totally possible, though Micah's writing "...from a third-party site" makes me want to confirm what he meant for sure. :P
is your app a web app (meaning it'd be subject to browser security measures, like CORS), or is it a mobile/desktop app, which generally have free reign to make whatever requests they'd like?
Well, both. It's a hybrid app built with Vue.js and Ionic - so primarily a web app. Yes, the request would normally be blocked by CORS just like all others to the Scratch API - I'm making the app's requests through a server (https://github.com/micahlt/itchy-api) that wraps functions of the Scratch API.
Or he might be running it in scratch console
Nope - that's much too complicated to provide a cohesive UX.
So technically everything is server-side, meaning that I phrased this incorrectly. Technically without a server or at least a CORS proxy it's not possible.
Got it, makes sense! If you'd like to document that, that's very much welcome - just be sure to include a note near the top explaining that CORS policies will prevent access through web browsers, and that only external apps (desktop, mobile, CLI) can access it.
Relatedly, although you didn't ask for input, I should still take responsibility to warn you about logging in through your own server (or any server) as a proxy: this requires users to send their password to you, and that has serious risks. If your server - or its provider - log in- or out-bound requests, users' passwords will be stored. If your server runs into any malware or security issues (which you should always assume it will), malicious actors could detect those requests and collect them for their own use. And you're also forcing users to trust you not to do anything bad with the passwords (or resultant session IDs) yourself, which is a big ask. As far as I can tell, the Scratch Team would be strongly opposed to a proxy for all these reasons, so you'd run a personal risk of getting into trouble with them, too.
(The same trust has to be given no matter the consumer of a password, of course. But here, you inevitably run clear risks (i.e. malware/security holes), whereas if the requests only ever go between the user's own machine and the official Scratch API, they only have to trust you, or the source code you've provided (that they may choose to build from), provided your app is open source. Sandboxing and the like can also (theoretically) be applied to keep the app from making requests to places besides Scratch, whereas depending on a proxy means users have no choice but to hope a black box is both trustworthy and secure!)
PS: Thanks for all your attention on this repo, lately and over the months! I'm looking at getting back into updating it, too - there are a lot of API endpoints I've catalogued in the issues over the years, and I really ought to give them a home in the actual documentation. So you'll have someone else actively working on the repo too! :)
If you'd like to document that, that's very much welcome - just be sure to include a note near the top explaining that CORS policies will prevent access through web browsers, and that only external apps (desktop, mobile, CLI) can access it.
Will do!
I should still take responsibility to warn you about logging in through your own server (or any server) as a proxy
I appreciate the warning - the servers I'm using are hosted by @vercel, which is a very reputable company that is known for providing hosting for developers (they're also the creators of Next.js). I definitely wouldn't host on my personal server as that's a huge security issue. Plus, I don't really want to port forward.
if the requests only ever go between the user's own machine and the official Scratch API, they only have to trust you, or the source code you've provided
Yes - but I'm hoping that users will be able to trust us since the proxy server's code is also open-sourced.
Thanks for all your attention on this repo
No problem at all - in fact at my workplace, we say it's our pleasure 😄 I'm just hoping to create a cohesive set of docs that is accessible to absolutely anyone, since Scratch Team has utterly failed to do so.
I appreciate the warning - the servers I'm using are hosted by @vercel, which is a very reputable company that is known for providing hosting for developers (they're also the creators of Next.js). I definitely wouldn't host on my personal server as that's a huge security issue. Plus, I don't really want to port forward.
That's a good precaution to take, but security vulnerabilities can occur in depended-upon packages as well. Server security can be more confident by depending on a service like Vercel, though it still can't be considered 100% perfect, and there are other areas where security issues can arise too. If an issue is ever discovered in any of those - be they your own proxy code, or NPM packages, used software versions, etc - those can be abused to steal passwords. As well, vulnerabilities can be found by malicious actors and left unreported, meaning there may be vulnerabilities left totally unknown (and unpatched), even in server software provided by e.g. Vercel. Like I mentioned, you should always assume vulnerabilities will come up - and thusly, do your best to prevent such vulnerabilities from being a problem in the first place.
To minimize security vulnerabilities, we ended up switching over to an Ionic plugin that will send requests directly to Scratch (bypassing our servers) through the native Android HTTP request interface. Thanks for your feedback, and I will at some point add documentation for this 😄
Okay, finally getting around to writing docs for this. I'll be submitting a PR very, very soon!
#71 is opened. An early apology for the mess of comments - I realized that I haven't pulled from your repo recently.