@letsmoe/otter-sdk 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +184 -2
- package/package.json +40 -4
- package/src/aes-gcm.ts +189 -0
- package/src/client.ts +23 -0
- package/src/context.ts +74 -0
- package/src/definition.ts +81 -0
- package/src/errors.ts +61 -0
- package/src/extract.ts +134 -0
- package/src/generated/index.ts +79 -0
- package/src/generated/runtime/batcher.ts +275 -0
- package/src/generated/runtime/createClient.ts +68 -0
- package/src/generated/runtime/error.ts +29 -0
- package/src/generated/runtime/fetcher.ts +97 -0
- package/src/generated/runtime/generateGraphqlOperation.ts +225 -0
- package/src/generated/runtime/index.ts +13 -0
- package/src/generated/runtime/linkTypeMap.ts +156 -0
- package/src/generated/runtime/typeSelection.ts +95 -0
- package/src/generated/runtime/types.ts +69 -0
- package/src/generated/schema.graphql +657 -0
- package/src/generated/schema.ts +1338 -0
- package/src/generated/types.ts +1495 -0
- package/src/hosters/dead-link.ts +55 -0
- package/src/hosters/dood.ts +69 -0
- package/src/hosters/filemoon.ts +152 -0
- package/src/hosters/generic.ts +63 -0
- package/src/hosters/index.ts +14 -0
- package/src/hosters/recaptcha.ts +61 -0
- package/src/hosters/registry.ts +74 -0
- package/src/hosters/streamtape.ts +63 -0
- package/src/hosters/vidara.ts +48 -0
- package/src/hosters/vinovo.ts +55 -0
- package/src/hosters/voe-decoding.ts +131 -0
- package/src/hosters/voe-domains.ts +39 -0
- package/src/hosters/voe.ts +82 -0
- package/src/http-client.ts +295 -0
- package/src/http.ts +97 -0
- package/src/index.ts +9 -0
- package/src/languages.ts +73 -0
- package/src/match.ts +120 -0
- package/src/model.ts +110 -0
- package/src/packer.ts +106 -0
- package/src/plugin.ts +4 -0
- package/src/run.ts +74 -0
- package/src/runtime.ts +254 -0
- package/src/testing.ts +120 -0
- package/src/timing.ts +11 -0
- package/src/types.ts +122 -0
- package/src/url.ts +60 -0
package/README.md
CHANGED
|
@@ -1,3 +1,185 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @letsmoe/otter-sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
TypeScript SDK for Otter plugins, and the typed GraphQL client for the backend.
|
|
4
|
+
|
|
5
|
+
A plugin does one or both of two things:
|
|
6
|
+
|
|
7
|
+
- **streams**: given a movie or episode TMDB already identified, find its links on a site.
|
|
8
|
+
- **sources**: given a hoster link, return a playable media URL.
|
|
9
|
+
|
|
10
|
+
Plugins run inside the backend, in an embedded JS engine (goja) on the NAS and on the phone, one fresh runtime per call. Only `fetch`, `URL`, `Buffer`, `AbortSignal.timeout`, `setTimeout` and `node-html-parser` exist there: no Node built-ins, no `atob`, no `TextDecoder`. The SDK helpers are written for that.
|
|
11
|
+
|
|
12
|
+
## Writing a plugin
|
|
13
|
+
|
|
14
|
+
A plugin is two files. `plugin.ts` only defines it, so tests can import it; `index.ts` is the bundle entry the backend executes.
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
// plugin.ts
|
|
18
|
+
import { definePlugin, type PluginContext } from "@letsmoe/otter-sdk/plugin";
|
|
19
|
+
import type { StreamListParams } from "@letsmoe/otter-sdk";
|
|
20
|
+
|
|
21
|
+
async function listStreams({ media }: StreamListParams, ctx: PluginContext) {
|
|
22
|
+
if (media.object !== "episode") return ctx.list([]);
|
|
23
|
+
|
|
24
|
+
const search = await ctx.http.get(`/serien?q=${encodeURIComponent(media.series.title)}`);
|
|
25
|
+
const root = await search.html();
|
|
26
|
+
const series = ctx.match.best(
|
|
27
|
+
root.querySelectorAll("a.series").map((link) => ({ title: link.text, href: link.getAttribute("href") || "" })),
|
|
28
|
+
media,
|
|
29
|
+
);
|
|
30
|
+
if (!series) return ctx.list([]); // not on this site: an empty list, not an error
|
|
31
|
+
|
|
32
|
+
const page = await ctx.http.get(`${series.href}/staffel-${media.season_number}/episode-${media.episode_number}`);
|
|
33
|
+
const buttons = (await page.html()).querySelectorAll("button[data-play-url]");
|
|
34
|
+
return ctx.list(
|
|
35
|
+
buttons.map((button) => ({
|
|
36
|
+
url: ctx.http.absolute(button.getAttribute("data-play-url") || ""),
|
|
37
|
+
language: "de",
|
|
38
|
+
})),
|
|
39
|
+
);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export default definePlugin({
|
|
43
|
+
id: "s-to",
|
|
44
|
+
name: "S.to",
|
|
45
|
+
version: "0.2.0",
|
|
46
|
+
base_url: "https://s.to",
|
|
47
|
+
languages: ["de"],
|
|
48
|
+
media: ["episode"],
|
|
49
|
+
streams: { list: listStreams },
|
|
50
|
+
});
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
// index.ts
|
|
55
|
+
import { runPlugin } from "@letsmoe/otter-sdk/plugin";
|
|
56
|
+
import plugin from "./plugin.ts";
|
|
57
|
+
|
|
58
|
+
runPlugin(plugin);
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`runPlugin` also still accepts the v1 shape `{ meta, streams(args), resolve(url) }`, so unported plugins keep working.
|
|
62
|
+
|
|
63
|
+
### Definition
|
|
64
|
+
|
|
65
|
+
| Field | |
|
|
66
|
+
| --- | --- |
|
|
67
|
+
| `id`, `name`, `version` | `id` is the stable key (settings, folder); `name` is shown in the UI |
|
|
68
|
+
| `description?`, `icon?` | emoji or URL |
|
|
69
|
+
| `base_url?` | the site. The backend shows it as an editable **Domain** setting for every plugin that has one and passes the user's value as `OTTER_BASE_URL`; `ctx.http` and `ctx.plugin.base_url` use it |
|
|
70
|
+
| `languages?`, `media?` | `["de"]`, `["movie", "episode"]` |
|
|
71
|
+
| `settings?` | extra fields; values arrive in `ctx.settings` |
|
|
72
|
+
| `streams?` | `{ list(params, ctx) }` returning `ctx.list(items)` |
|
|
73
|
+
| `subtitles?` | `{ list({ media, languages }, ctx) }` returning `ctx.list(SubtitleInput[])`; `SubtitleInput` is `{ url, language (ISO 639-1), format? ("srt" default | "vtt"), label?, release?, hearing_impaired?, headers? }` |
|
|
74
|
+
| `sources?` | `{ domains, fallback?, retrieve(params, ctx) }`; `fallback: true` also takes any other domain |
|
|
75
|
+
|
|
76
|
+
### Objects
|
|
77
|
+
|
|
78
|
+
Every object has an `object` tag, ids are strings, fields are snake_case.
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
streams.list(params: { media: MovieRef | EpisodeRef }, ctx) => List<StreamInput>
|
|
82
|
+
// MovieRef { object: "movie", id: "movie:603", title, original_title?, year?, tmdb_id?, imdb_id? }
|
|
83
|
+
// EpisodeRef { object: "episode", id: "episode:<tmdb>:<season>:<episode>", series: SeriesRef, season_number, episode_number }
|
|
84
|
+
// StreamInput { url, label?, quality?, language?, format?, size_bytes? } label defaults to the hoster's name, else the domain
|
|
85
|
+
|
|
86
|
+
sources.retrieve({ url }, ctx) => SourceInput // { url, mime_type, headers?, quality? }
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
The SDK adds `object: "stream"` / `"source"` and converts to the backend's wire format (`{ downloads }` / `ResolveResult`).
|
|
90
|
+
|
|
91
|
+
### `ctx`
|
|
92
|
+
|
|
93
|
+
- **`ctx.http`**: `get(url, options?)`, `post(url, { body | json, ... })`, `finalUrl(url)`, `absolute(path)`. Options: `headers`, `referer`, `timeout_ms` (15 s), `retries` (2, for network errors and 5xx, never 4xx), `allow_error_status`, `follow_redirects`. Responses have `.text()`, `.json()`, `.html()` (node-html-parser root), `.response()`, `.status`, `.url`. Browser User-Agent and an Accept-Language from `languages` are set. A Cloudflare challenge throws `PluginBlockedError` (or goes through FlareSolverr when `FLARESOLVERR_URL` is set); 429 throws `PluginRateLimitError`; 5xx and unreachable sites throw `PluginSourceError("source_offline")`; other 4xx throw `HttpError`.
|
|
94
|
+
- **`ctx.match`**: `normalize(title)` lowercases, folds umlauts (ä to ae, ß to ss) and accents, drops apostrophes, collapses punctuation. `titles(candidate, media)` compares against the title and original title (of the series for an episode), ignoring a trailing "(1999)", a leading the/der/die/das and and/und/&. `best(candidates, media, { title?, year? })` returns the candidate with an exactly matching title; the year (plus or minus one) only decides between several.
|
|
95
|
+
- **`ctx.extract`**: `mediaUrls(html)` (m3u8/mpd/mp4/webm, also inside packed scripts), `unpack(html)` (Dean Edwards packer), `iframes(html, pageUrl)`, `scriptJson(html, name)`, `base64(text)` (URL-safe and unpadded too), `mimeType(url, fallback?)`.
|
|
96
|
+
- **`ctx.hosters`**: see below. **`ctx.settings`**: declared settings by key. **`ctx.log(message, data?)`**: stderr. **`ctx.list(items)`**.
|
|
97
|
+
|
|
98
|
+
### Hosters
|
|
99
|
+
|
|
100
|
+
`@letsmoe/otter-sdk/hosters` holds the extractors for file hosters: VOE, Vidara, Doodstream, Filemoon, Streamtape, Vinovo, and a generic page scanner for everything else.
|
|
101
|
+
|
|
102
|
+
```ts
|
|
103
|
+
hosters.retrieve(url, ctx) // the hoster serving the link, else the generic scanner
|
|
104
|
+
hosters.supports(url); hosters.nameOf(url); hosters.domains();
|
|
105
|
+
|
|
106
|
+
export const myHoster = defineHoster({
|
|
107
|
+
name: "MyHoster",
|
|
108
|
+
domains: ["myhoster.example"],
|
|
109
|
+
async retrieve(url, ctx) {
|
|
110
|
+
const page = await (await ctx.http.get(url)).text();
|
|
111
|
+
const [media] = ctx.extract.mediaUrls(page);
|
|
112
|
+
if (!media) throw new PluginSourceError("extraction_failed", `no stream on ${url}`);
|
|
113
|
+
return { url: media.url, mime_type: media.mime_type, headers: { Referer: url } };
|
|
114
|
+
},
|
|
115
|
+
});
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
A resolver plugin is `sources: { domains: hosters.domains(), fallback: true, retrieve: ({ url }, ctx) => ctx.hosters.retrieve(url, ctx) }`.
|
|
119
|
+
|
|
120
|
+
### Errors
|
|
121
|
+
|
|
122
|
+
`OtterError(type, message, { code?, status? })` and `PluginBlockedError` (`blocked`), `PluginSourceError` (`source_offline` | `extraction_failed`), `PluginRateLimitError` (`rate_limited`), `PluginDeadLinkError` (`dead_link`: the hoster says the file was deleted or never existed, so the backend drops the link; throw it only for an explicit answer about that one link, never for a failed, blocked or empty request), `HttpError`. `runPlugin` answers `{ "error": "...", "code": "blocked" }`; the backend turns the code into `*plugins.PluginError`. A title that is not on the site is an empty list, never an error.
|
|
123
|
+
|
|
124
|
+
### Testing
|
|
125
|
+
|
|
126
|
+
```ts
|
|
127
|
+
import { testPlugin, movie, episode, fixtures } from "@letsmoe/otter-sdk/testing";
|
|
128
|
+
import plugin from "../plugin.ts";
|
|
129
|
+
|
|
130
|
+
const subject = testPlugin(plugin, { fetch: fixtures(`${import.meta.dir}/fixtures`) });
|
|
131
|
+
const streams = await subject.streams.list({ media: episode({ series: "Dark", tmdb_id: 70523 }, 1, 2) });
|
|
132
|
+
expect(streams.data[0].url).toBe("https://voe.sx/e/abc");
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
`testPlugin` runs the handlers with a real `ctx` (pass `env` to set `OTTER_BASE_URL` or settings) and returns the completed `list`/`source` objects. `fixtures(dir)` replaces the network: a request is served from the file named after its URL, `<host>_<path>_<query>` with every other character as `_`, with or without `.html`/`.json`/`.js`/`.txt`, first with the query string, then without. `https://s.to/serie/dark?x=1` is `s.to_serie_dark_x_1.html`, then `s.to_serie_dark.html`. Non-GET requests use the same name prefixed by the lowercase method (`post.s.to_api_login`). Anything else answers 404 and logs the expected name.
|
|
136
|
+
|
|
137
|
+
### Bundling
|
|
138
|
+
|
|
139
|
+
`cd apps/backend && bun scripts/bundle-plugins.ts` bundles every plugin into one CommonJS file (`node-html-parser` stays external; the backend provides it natively).
|
|
140
|
+
|
|
141
|
+
## Data client
|
|
142
|
+
|
|
143
|
+
A fully-typed client over the backend GraphQL API, for both plugins and the frontend. Built on a [genql](https://genql.dev)-generated client (`src/generated`, regenerate with `bun run codegen`) wrapped in an ergonomic per-resource facade.
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
import { createOtterClient } from "@letsmoe/otter-sdk/client";
|
|
147
|
+
|
|
148
|
+
const otter = createOtterClient({ url: "http://localhost:8080/graphql" });
|
|
149
|
+
|
|
150
|
+
const movies = await otter.movie.list({ limit: 50 }); // search/limit/offset
|
|
151
|
+
const movie = await otter.movie.get(id); // by id
|
|
152
|
+
const made = await otter.movie.create({ tmdbId: 603, title: "The Matrix", originalTitle: "The Matrix" });
|
|
153
|
+
await otter.movie.update(id, { tagline: "..." });
|
|
154
|
+
await otter.movie.remove(id);
|
|
155
|
+
|
|
156
|
+
const seasons = await otter.season.list({ seriesId }); // child lists take their parent id
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Every read/write returns **all scalar fields** by default. Pass a genql selection as the last argument to pick fields or pull in relations — return types narrow to match:
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
const slim = await otter.movie.get(id, { id: true, title: true }); // typed as { id, title } | null
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Resources: `movie`, `series`, `season`, `episode`, `person`, `collection`, `genre`, `keyword`, `network`, `productionCompany`, `watchProvider`, `credit`, `image`, `video`. Each exposes `get`, `list`, `create`, `update`, `remove`.
|
|
166
|
+
|
|
167
|
+
For subscriptions, settings, and bespoke mutations not covered by the facade, use the raw genql client:
|
|
168
|
+
|
|
169
|
+
```ts
|
|
170
|
+
const { jobs } = await otter.client.query({ jobs: { id: true, status: true } });
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Regenerate the typed client whenever the backend schema changes:
|
|
174
|
+
|
|
175
|
+
```sh
|
|
176
|
+
bun run codegen # concatenates apps/backend SDL -> runs genql -> src/generated
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
## Protocol
|
|
180
|
+
|
|
181
|
+
The backend runs a plugin by writing `{ "capability": "meta" | "streams" | "resolve" | "subtitles", "args": {...} }` to its stdin and reads one line from stdout: `{ "result": ... }` or `{ "error": "...", "code"?: "blocked" | "source_offline" | "extraction_failed" | "rate_limited" | "dead_link" }`. The wire types (`PluginMeta`, `StreamsArgs`, `Download`, `ResolveResult`) in `src/types.ts` mirror `apps/backend/internal/plugins/types.go`.
|
|
182
|
+
|
|
183
|
+
## License
|
|
184
|
+
|
|
185
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,42 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@letsmoe/otter-sdk",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"private": false,
|
|
5
|
+
"author": {
|
|
6
|
+
"name": "Letsmoe",
|
|
7
|
+
"url": "https://letsmoe.com"
|
|
8
|
+
},
|
|
9
|
+
"description": "SDK for writing Otter plugins",
|
|
10
|
+
"repository": {
|
|
11
|
+
"type": "git",
|
|
12
|
+
"url": "git+https://github.com/Letsmoe/otter.git",
|
|
13
|
+
"directory": "packages/otter-sdk"
|
|
14
|
+
},
|
|
15
|
+
"files": [
|
|
16
|
+
"src",
|
|
17
|
+
"README.md"
|
|
18
|
+
],
|
|
19
|
+
"type": "module",
|
|
20
|
+
"scripts": {
|
|
21
|
+
"codegen": "bun run scripts/codegen.ts",
|
|
22
|
+
"typecheck": "tsc --noEmit",
|
|
23
|
+
"test": "bun test"
|
|
24
|
+
},
|
|
25
|
+
"exports": {
|
|
26
|
+
".": "./src/index.ts",
|
|
27
|
+
"./types": "./src/types.ts",
|
|
28
|
+
"./http": "./src/http.ts",
|
|
29
|
+
"./plugin": "./src/plugin.ts",
|
|
30
|
+
"./hosters": "./src/hosters/index.ts",
|
|
31
|
+
"./testing": "./src/testing.ts",
|
|
32
|
+
"./client": "./src/client.ts",
|
|
33
|
+
"./generated": "./src/generated/index.ts"
|
|
34
|
+
},
|
|
35
|
+
"devDependencies": {
|
|
36
|
+
"@genql/cli": "^6.3.4"
|
|
37
|
+
},
|
|
38
|
+
"dependencies": {
|
|
39
|
+
"@genql/runtime": "^2.10.0",
|
|
40
|
+
"node-html-parser": "^6.1.13"
|
|
41
|
+
}
|
|
42
|
+
}
|
package/src/aes-gcm.ts
ADDED
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
// AES-GCM decryption in plain JS: the plugin runtime has neither crypto.subtle nor node:crypto.
|
|
2
|
+
|
|
3
|
+
const BLOCK_SIZE = 16;
|
|
4
|
+
const GCM_TAG_LENGTH = 16;
|
|
5
|
+
const GCM_NONCE_LENGTH = 12;
|
|
6
|
+
const FIELD_POLYNOMIAL = 0x11b;
|
|
7
|
+
|
|
8
|
+
interface AesTables {
|
|
9
|
+
substitutionBox: Uint8Array;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
let cachedTables: AesTables | undefined;
|
|
13
|
+
|
|
14
|
+
function multiplyInField(left: number, right: number): number {
|
|
15
|
+
let product = 0;
|
|
16
|
+
let factor = left;
|
|
17
|
+
let remaining = right;
|
|
18
|
+
while (remaining > 0) {
|
|
19
|
+
if (remaining & 1) product ^= factor;
|
|
20
|
+
factor <<= 1;
|
|
21
|
+
if (factor & 0x100) factor ^= FIELD_POLYNOMIAL;
|
|
22
|
+
remaining >>= 1;
|
|
23
|
+
}
|
|
24
|
+
return product;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function rotateLeft(value: number, bits: number): number {
|
|
28
|
+
return ((value << bits) | (value >> (8 - bits))) & 0xff;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** The S-box derived from its definition: multiplicative inverse in GF(2^8), then the affine transform. */
|
|
32
|
+
function buildSubstitutionBox(): Uint8Array {
|
|
33
|
+
const box = new Uint8Array(256);
|
|
34
|
+
const inverses = new Uint8Array(256);
|
|
35
|
+
for (let value = 1; value < 256; value++) {
|
|
36
|
+
for (let candidate = 1; candidate < 256; candidate++) {
|
|
37
|
+
if (multiplyInField(value, candidate) === 1) inverses[value] = candidate;
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
for (let value = 0; value < 256; value++) {
|
|
41
|
+
const inverse = inverses[value];
|
|
42
|
+
box[value] = inverse ^ rotateLeft(inverse, 1) ^ rotateLeft(inverse, 2) ^ rotateLeft(inverse, 3) ^ rotateLeft(inverse, 4) ^ 0x63;
|
|
43
|
+
}
|
|
44
|
+
return box;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
function tables(): AesTables {
|
|
48
|
+
if (!cachedTables) cachedTables = { substitutionBox: buildSubstitutionBox() };
|
|
49
|
+
return cachedTables;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** Round keys for a 16, 24 or 32 byte key, as one flat byte array of 16 bytes per round. */
|
|
53
|
+
function expandKey(key: Uint8Array, substitutionBox: Uint8Array): Uint8Array {
|
|
54
|
+
const keyWords = key.length / 4;
|
|
55
|
+
const rounds = keyWords + 6;
|
|
56
|
+
const expanded = new Uint8Array(BLOCK_SIZE * (rounds + 1));
|
|
57
|
+
expanded.set(key);
|
|
58
|
+
let roundConstant = 1;
|
|
59
|
+
for (let word = keyWords; word < 4 * (rounds + 1); word++) {
|
|
60
|
+
const previous = expanded.slice((word - 1) * 4, word * 4);
|
|
61
|
+
if (word % keyWords === 0) {
|
|
62
|
+
previous.set([substitutionBox[previous[1]] ^ roundConstant, substitutionBox[previous[2]], substitutionBox[previous[3]], substitutionBox[previous[0]]]);
|
|
63
|
+
roundConstant = multiplyInField(roundConstant, 2);
|
|
64
|
+
} else if (keyWords > 6 && word % keyWords === 4) {
|
|
65
|
+
for (let index = 0; index < 4; index++) previous[index] = substitutionBox[previous[index]];
|
|
66
|
+
}
|
|
67
|
+
for (let index = 0; index < 4; index++) {
|
|
68
|
+
expanded[word * 4 + index] = expanded[(word - keyWords) * 4 + index] ^ previous[index];
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
return expanded;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function addRoundKey(state: Uint8Array, roundKeys: Uint8Array, round: number): void {
|
|
75
|
+
for (let index = 0; index < BLOCK_SIZE; index++) state[index] ^= roundKeys[round * BLOCK_SIZE + index];
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
function substituteBytes(state: Uint8Array, substitutionBox: Uint8Array): void {
|
|
79
|
+
for (let index = 0; index < BLOCK_SIZE; index++) state[index] = substitutionBox[state[index]];
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** The state is column-major, so row r of column c sits at index c * 4 + r. */
|
|
83
|
+
function shiftRows(state: Uint8Array): void {
|
|
84
|
+
const copy = state.slice();
|
|
85
|
+
for (let column = 0; column < 4; column++) {
|
|
86
|
+
for (let row = 0; row < 4; row++) state[column * 4 + row] = copy[((column + row) % 4) * 4 + row];
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function mixColumns(state: Uint8Array): void {
|
|
91
|
+
for (let column = 0; column < 4; column++) {
|
|
92
|
+
const [a, b, c, d] = state.slice(column * 4, column * 4 + 4);
|
|
93
|
+
state[column * 4] = multiplyInField(a, 2) ^ multiplyInField(b, 3) ^ c ^ d;
|
|
94
|
+
state[column * 4 + 1] = a ^ multiplyInField(b, 2) ^ multiplyInField(c, 3) ^ d;
|
|
95
|
+
state[column * 4 + 2] = a ^ b ^ multiplyInField(c, 2) ^ multiplyInField(d, 3);
|
|
96
|
+
state[column * 4 + 3] = multiplyInField(a, 3) ^ b ^ c ^ multiplyInField(d, 2);
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
function encryptBlock(block: Uint8Array, roundKeys: Uint8Array, substitutionBox: Uint8Array): Uint8Array {
|
|
101
|
+
const rounds = roundKeys.length / BLOCK_SIZE - 1;
|
|
102
|
+
const state = block.slice();
|
|
103
|
+
addRoundKey(state, roundKeys, 0);
|
|
104
|
+
for (let round = 1; round < rounds; round++) {
|
|
105
|
+
substituteBytes(state, substitutionBox);
|
|
106
|
+
shiftRows(state);
|
|
107
|
+
mixColumns(state);
|
|
108
|
+
addRoundKey(state, roundKeys, round);
|
|
109
|
+
}
|
|
110
|
+
substituteBytes(state, substitutionBox);
|
|
111
|
+
shiftRows(state);
|
|
112
|
+
addRoundKey(state, roundKeys, rounds);
|
|
113
|
+
return state;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
function incrementCounter(counter: Uint8Array): void {
|
|
117
|
+
for (let index = BLOCK_SIZE - 1; index >= BLOCK_SIZE - 4; index--) {
|
|
118
|
+
counter[index] = (counter[index] + 1) & 0xff;
|
|
119
|
+
if (counter[index] !== 0) return;
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/** Multiplication in GF(2^128) with GCM's bit order. */
|
|
124
|
+
function multiplyHash(left: Uint8Array, right: Uint8Array): Uint8Array {
|
|
125
|
+
const result = new Uint8Array(BLOCK_SIZE);
|
|
126
|
+
const shifted = right.slice();
|
|
127
|
+
for (let bit = 0; bit < 128; bit++) {
|
|
128
|
+
if (left[bit >> 3] & (0x80 >> (bit & 7))) {
|
|
129
|
+
for (let index = 0; index < BLOCK_SIZE; index++) result[index] ^= shifted[index];
|
|
130
|
+
}
|
|
131
|
+
const carry = shifted[BLOCK_SIZE - 1] & 1;
|
|
132
|
+
for (let index = BLOCK_SIZE - 1; index > 0; index--) shifted[index] = (shifted[index] >> 1) | ((shifted[index - 1] & 1) << 7);
|
|
133
|
+
shifted[0] >>= 1;
|
|
134
|
+
if (carry) shifted[0] ^= 0xe1;
|
|
135
|
+
}
|
|
136
|
+
return result;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
function ghash(hashKey: Uint8Array, ciphertext: Uint8Array): Uint8Array {
|
|
140
|
+
let digest: Uint8Array = new Uint8Array(BLOCK_SIZE);
|
|
141
|
+
const lengthBlock = new Uint8Array(BLOCK_SIZE);
|
|
142
|
+
new DataView(lengthBlock.buffer).setUint32(12, ciphertext.length * 8);
|
|
143
|
+
for (let offset = 0; offset < ciphertext.length; offset += BLOCK_SIZE) {
|
|
144
|
+
const block = ciphertext.subarray(offset, offset + BLOCK_SIZE);
|
|
145
|
+
for (let index = 0; index < block.length; index++) digest[index] ^= block[index];
|
|
146
|
+
digest = multiplyHash(digest, hashKey);
|
|
147
|
+
}
|
|
148
|
+
for (let index = 0; index < BLOCK_SIZE; index++) digest[index] ^= lengthBlock[index];
|
|
149
|
+
return multiplyHash(digest, hashKey);
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
function tagsMatch(expected: Uint8Array, actual: Uint8Array): boolean {
|
|
153
|
+
let difference = 0;
|
|
154
|
+
for (let index = 0; index < GCM_TAG_LENGTH; index++) difference |= expected[index] ^ actual[index];
|
|
155
|
+
return difference === 0;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Decrypts `ciphertext || 16 byte tag` (no additional data, 12 byte nonce) and checks the tag.
|
|
160
|
+
* Throws when the key, nonce or data is wrong.
|
|
161
|
+
*/
|
|
162
|
+
export function decryptAesGcm(key: Uint8Array, nonce: Uint8Array, encrypted: Uint8Array): Uint8Array {
|
|
163
|
+
if (key.length !== 16 && key.length !== 24 && key.length !== 32) throw new Error("AES-GCM: invalid key length");
|
|
164
|
+
if (nonce.length !== GCM_NONCE_LENGTH) throw new Error("AES-GCM: only 12 byte nonces are supported");
|
|
165
|
+
if (encrypted.length < GCM_TAG_LENGTH) throw new Error("AES-GCM: data shorter than the tag");
|
|
166
|
+
|
|
167
|
+
const { substitutionBox } = tables();
|
|
168
|
+
const roundKeys = expandKey(key, substitutionBox);
|
|
169
|
+
const ciphertext = encrypted.subarray(0, encrypted.length - GCM_TAG_LENGTH);
|
|
170
|
+
const tag = encrypted.subarray(encrypted.length - GCM_TAG_LENGTH);
|
|
171
|
+
|
|
172
|
+
const counter = new Uint8Array(BLOCK_SIZE);
|
|
173
|
+
counter.set(nonce);
|
|
174
|
+
counter[BLOCK_SIZE - 1] = 1;
|
|
175
|
+
const tagMask = encryptBlock(counter, roundKeys, substitutionBox);
|
|
176
|
+
const hashKey = encryptBlock(new Uint8Array(BLOCK_SIZE), roundKeys, substitutionBox);
|
|
177
|
+
const expectedTag = ghash(hashKey, ciphertext);
|
|
178
|
+
for (let index = 0; index < BLOCK_SIZE; index++) expectedTag[index] ^= tagMask[index];
|
|
179
|
+
if (!tagsMatch(expectedTag, tag)) throw new Error("AES-GCM: authentication failed");
|
|
180
|
+
|
|
181
|
+
const plaintext = new Uint8Array(ciphertext.length);
|
|
182
|
+
for (let offset = 0; offset < ciphertext.length; offset += BLOCK_SIZE) {
|
|
183
|
+
incrementCounter(counter);
|
|
184
|
+
const keystream = encryptBlock(counter, roundKeys, substitutionBox);
|
|
185
|
+
const blockLength = Math.min(BLOCK_SIZE, ciphertext.length - offset);
|
|
186
|
+
for (let index = 0; index < blockLength; index++) plaintext[offset + index] = ciphertext[offset + index] ^ keystream[index];
|
|
187
|
+
}
|
|
188
|
+
return plaintext;
|
|
189
|
+
}
|
package/src/client.ts
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
// Typed GraphQL client over the Otter API (genql, generated from the
|
|
2
|
+
// backend schema by `bun run codegen`).
|
|
3
|
+
//
|
|
4
|
+
// const otter = createOtterClient({ url: "http://localhost:8080/graphql" });
|
|
5
|
+
// const { title } = await otter.query({ title: { __args: { id: "movie:603" }, title: true } });
|
|
6
|
+
|
|
7
|
+
import { createClient, type Client } from "./generated/index";
|
|
8
|
+
|
|
9
|
+
export interface OtterClientOptions {
|
|
10
|
+
/** GraphQL endpoint, e.g. http://localhost:8080/graphql */
|
|
11
|
+
url: string;
|
|
12
|
+
headers?: Record<string, string>;
|
|
13
|
+
/** Custom fetch (defaults to global fetch). */
|
|
14
|
+
fetch?: typeof fetch;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
export type OtterClient = Client;
|
|
18
|
+
|
|
19
|
+
export function createOtterClient(options: OtterClientOptions): OtterClient {
|
|
20
|
+
return createClient({ url: options.url, headers: options.headers, fetch: options.fetch });
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export * from "./generated/index";
|
package/src/context.ts
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import type { PluginContext, PluginDefinition } from "./definition.ts";
|
|
2
|
+
import { extract } from "./extract.ts";
|
|
3
|
+
import { hosters } from "./hosters/index.ts";
|
|
4
|
+
import { createHttpClient } from "./http-client.ts";
|
|
5
|
+
import { match } from "./match.ts";
|
|
6
|
+
import type { List } from "./model.ts";
|
|
7
|
+
|
|
8
|
+
/** Env var through which the backend passes the user's override of base_url. */
|
|
9
|
+
export const BASE_URL_ENV_KEY = "OTTER_BASE_URL";
|
|
10
|
+
|
|
11
|
+
export interface ContextOptions {
|
|
12
|
+
/** Replaces the global fetch, for tests. */
|
|
13
|
+
fetch?: typeof fetch;
|
|
14
|
+
/** Replaces process.env, for tests. */
|
|
15
|
+
env?: Record<string, string | undefined>;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/** The user's override of base_url if set, else the declared one; without trailing slash. */
|
|
19
|
+
export function effectiveBaseUrl(
|
|
20
|
+
definition: PluginDefinition,
|
|
21
|
+
env: Record<string, string | undefined>,
|
|
22
|
+
): string | undefined {
|
|
23
|
+
const override = (env[BASE_URL_ENV_KEY] || "").trim();
|
|
24
|
+
const chosen = override || definition.base_url;
|
|
25
|
+
if (!chosen) return undefined;
|
|
26
|
+
return chosen.replace(/\/+$/, "");
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function settingsOf(
|
|
30
|
+
definition: PluginDefinition,
|
|
31
|
+
env: Record<string, string | undefined>,
|
|
32
|
+
): Record<string, string> {
|
|
33
|
+
const settings: Record<string, string> = {};
|
|
34
|
+
for (const field of definition.settings || []) {
|
|
35
|
+
const value = env[field.key] || field.default;
|
|
36
|
+
if (value !== undefined) settings[field.key] = value;
|
|
37
|
+
}
|
|
38
|
+
return settings;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
function describe(data: unknown): string {
|
|
42
|
+
if (data === undefined) return "";
|
|
43
|
+
try {
|
|
44
|
+
return " " + JSON.stringify(data);
|
|
45
|
+
} catch {
|
|
46
|
+
return " " + String(data);
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export function createContext(definition: PluginDefinition, options: ContextOptions = {}): PluginContext {
|
|
51
|
+
const env = options.env || process.env;
|
|
52
|
+
const baseUrl = effectiveBaseUrl(definition, env);
|
|
53
|
+
const languages = definition.languages || [];
|
|
54
|
+
return {
|
|
55
|
+
plugin: {
|
|
56
|
+
id: definition.id,
|
|
57
|
+
name: definition.name,
|
|
58
|
+
version: definition.version,
|
|
59
|
+
base_url: baseUrl,
|
|
60
|
+
languages,
|
|
61
|
+
},
|
|
62
|
+
http: createHttpClient({ baseUrl, languages, fetch: options.fetch }),
|
|
63
|
+
match,
|
|
64
|
+
extract,
|
|
65
|
+
hosters,
|
|
66
|
+
settings: settingsOf(definition, env),
|
|
67
|
+
log(message: string, data?: unknown): void {
|
|
68
|
+
console.error(`[${definition.id}] ${message}${describe(data)}`);
|
|
69
|
+
},
|
|
70
|
+
list<Item>(items: Item[]): List<Item> {
|
|
71
|
+
return { object: "list", data: items };
|
|
72
|
+
},
|
|
73
|
+
};
|
|
74
|
+
}
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
import type { HosterRegistry } from "./hosters/registry.ts";
|
|
2
|
+
import type { Extractor } from "./extract.ts";
|
|
3
|
+
import type { HttpClient } from "./http-client.ts";
|
|
4
|
+
import type { Matcher } from "./match.ts";
|
|
5
|
+
import type {
|
|
6
|
+
List,
|
|
7
|
+
MediaKind,
|
|
8
|
+
SourceInput,
|
|
9
|
+
SourceRetrieveParams,
|
|
10
|
+
StreamInput,
|
|
11
|
+
StreamListParams,
|
|
12
|
+
SubtitleInput,
|
|
13
|
+
SubtitleListParams,
|
|
14
|
+
} from "./model.ts";
|
|
15
|
+
import type { PluginSettingField } from "./types.ts";
|
|
16
|
+
|
|
17
|
+
/** Everything a handler needs, so plugins don't carry their own copies of these helpers. */
|
|
18
|
+
export interface PluginContext {
|
|
19
|
+
plugin: {
|
|
20
|
+
id: string;
|
|
21
|
+
name: string;
|
|
22
|
+
version: string;
|
|
23
|
+
/** The effective base URL: the user's override, else the declared one. */
|
|
24
|
+
base_url?: string;
|
|
25
|
+
languages: string[];
|
|
26
|
+
};
|
|
27
|
+
http: HttpClient;
|
|
28
|
+
match: Matcher;
|
|
29
|
+
extract: Extractor;
|
|
30
|
+
hosters: HosterRegistry;
|
|
31
|
+
/** Values of the settings the plugin declares (default applied), by key. */
|
|
32
|
+
settings: Record<string, string>;
|
|
33
|
+
/** Writes to stderr, prefixed with the plugin id. */
|
|
34
|
+
log(message: string, data?: unknown): void;
|
|
35
|
+
list<Item>(items: Item[]): List<Item>;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export interface StreamsCapability {
|
|
39
|
+
/** Finds the links to a movie or episode on the site. Not finding it is an empty list, not an error. */
|
|
40
|
+
list(params: StreamListParams, ctx: PluginContext): Promise<List<StreamInput>>;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export interface SubtitlesCapability {
|
|
44
|
+
/** Finds caption files for a movie or episode. Finding none is an empty list, not an error. */
|
|
45
|
+
list(params: SubtitleListParams, ctx: PluginContext): Promise<List<SubtitleInput>>;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export interface SourcesCapability {
|
|
49
|
+
/** Hostnames of the links this plugin can turn into media URLs. */
|
|
50
|
+
domains: string[];
|
|
51
|
+
/** Also handle links on any other domain. */
|
|
52
|
+
fallback?: boolean;
|
|
53
|
+
retrieve(params: SourceRetrieveParams, ctx: PluginContext): Promise<SourceInput>;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
export interface PluginDefinition {
|
|
57
|
+
/** Stable identifier; the settings key and the folder name. */
|
|
58
|
+
id: string;
|
|
59
|
+
/** Display name. */
|
|
60
|
+
name: string;
|
|
61
|
+
version: string;
|
|
62
|
+
description?: string;
|
|
63
|
+
/** Emoji or URL. */
|
|
64
|
+
icon?: string;
|
|
65
|
+
/** The site's address. The user can point it at a mirror in the plugin's settings. */
|
|
66
|
+
base_url?: string;
|
|
67
|
+
/** Languages of the site's content, most important first: "de", "en", ... */
|
|
68
|
+
languages?: string[];
|
|
69
|
+
media?: MediaKind[];
|
|
70
|
+
settings?: PluginSettingField[];
|
|
71
|
+
/** The site only works through FlareSolverr. */
|
|
72
|
+
requires_solver?: boolean;
|
|
73
|
+
streams?: StreamsCapability;
|
|
74
|
+
sources?: SourcesCapability;
|
|
75
|
+
subtitles?: SubtitlesCapability;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** Declares a plugin. Does nothing else: `runPlugin(plugin)` in the bundle entry runs it. */
|
|
79
|
+
export function definePlugin(definition: PluginDefinition): PluginDefinition {
|
|
80
|
+
return definition;
|
|
81
|
+
}
|
package/src/errors.ts
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/** Why a plugin call failed, in terms the backend can act on. */
|
|
2
|
+
export type ErrorCode = "blocked" | "source_offline" | "extraction_failed" | "rate_limited" | "dead_link";
|
|
3
|
+
|
|
4
|
+
export interface OtterErrorOptions {
|
|
5
|
+
code?: ErrorCode;
|
|
6
|
+
status?: number;
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
/** Base class of every error the SDK throws; `runPlugin` reports its `code` to the backend. */
|
|
10
|
+
export class OtterError extends Error {
|
|
11
|
+
readonly type: string;
|
|
12
|
+
readonly code?: ErrorCode;
|
|
13
|
+
readonly status?: number;
|
|
14
|
+
|
|
15
|
+
constructor(type: string, message: string, options: OtterErrorOptions = {}) {
|
|
16
|
+
super(message);
|
|
17
|
+
this.name = type;
|
|
18
|
+
this.type = type;
|
|
19
|
+
this.code = options.code;
|
|
20
|
+
this.status = options.status;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** The site refused us, typically with a Cloudflare challenge. */
|
|
25
|
+
export class PluginBlockedError extends OtterError {
|
|
26
|
+
constructor(message: string, status?: number) {
|
|
27
|
+
super("blocked_error", message, { code: "blocked", status });
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** The site or a hoster is down, or a link no longer yields a stream. */
|
|
32
|
+
export class PluginSourceError extends OtterError {
|
|
33
|
+
constructor(code: "source_offline" | "extraction_failed", message: string, status?: number) {
|
|
34
|
+
super("source_error", message, { code, status });
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* The hoster says the file is gone: it was deleted or never existed. Unlike
|
|
40
|
+
* `PluginSourceError` this is permanent, so the backend drops the link. Throw
|
|
41
|
+
* it only when the hoster answers explicitly for that one link, never because
|
|
42
|
+
* a request failed, was blocked or the extractor found nothing.
|
|
43
|
+
*/
|
|
44
|
+
export class PluginDeadLinkError extends OtterError {
|
|
45
|
+
constructor(message: string, status?: number) {
|
|
46
|
+
super("dead_link_error", message, { code: "dead_link", status });
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export class PluginRateLimitError extends OtterError {
|
|
51
|
+
constructor(message: string, status?: number) {
|
|
52
|
+
super("rate_limit_error", message, { code: "rate_limited", status });
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** A response with a status the plugin did not expect, and no more specific meaning. */
|
|
57
|
+
export class HttpError extends OtterError {
|
|
58
|
+
constructor(message: string, status: number) {
|
|
59
|
+
super("http_error", message, { status });
|
|
60
|
+
}
|
|
61
|
+
}
|