@vol-a/client 0.0.0-stage → 1.1.1
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/LICENSE +21 -0
- package/README.md +254 -2
- package/dist/body.d.ts +40 -0
- package/dist/body.d.ts.map +1 -0
- package/dist/body.js +112 -0
- package/dist/body.js.map +1 -0
- package/dist/client.d.ts +161 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +245 -0
- package/dist/client.js.map +1 -0
- package/dist/env.d.ts +19 -0
- package/dist/env.d.ts.map +1 -0
- package/dist/env.js +52 -0
- package/dist/env.js.map +1 -0
- package/dist/errors.d.ts +43 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +93 -0
- package/dist/errors.js.map +1 -0
- package/dist/files.d.ts +144 -0
- package/dist/files.d.ts.map +1 -0
- package/dist/files.js +239 -0
- package/dist/files.js.map +1 -0
- package/dist/folders.d.ts +35 -0
- package/dist/folders.d.ts.map +1 -0
- package/dist/folders.js +62 -0
- package/dist/folders.js.map +1 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +11 -0
- package/dist/index.js.map +1 -0
- package/dist/keyrings.d.ts +44 -0
- package/dist/keyrings.d.ts.map +1 -0
- package/dist/keyrings.js +111 -0
- package/dist/keyrings.js.map +1 -0
- package/dist/management.d.ts +47 -0
- package/dist/management.d.ts.map +1 -0
- package/dist/management.js +65 -0
- package/dist/management.js.map +1 -0
- package/dist/shares.d.ts +87 -0
- package/dist/shares.d.ts.map +1 -0
- package/dist/shares.js +144 -0
- package/dist/shares.js.map +1 -0
- package/dist/uploads.d.ts +112 -0
- package/dist/uploads.d.ts.map +1 -0
- package/dist/uploads.js +290 -0
- package/dist/uploads.js.map +1 -0
- package/package.json +48 -3
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"management.d.ts","sourceRoot":"","sources":["../src/management.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,aAAa,EAElB,KAAK,UAAU,EAIf,KAAK,YAAY,EAEjB,KAAK,WAAW,EAEhB,KAAK,cAAc,EAEpB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE3D,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACjC;AAED,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC9C,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AAED,uCAAuC;AACvC,qBAAa,QAAQ;IACP,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,UAAU;IAE/C,2GAA2G;IAC3G,MAAM,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAOxD,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAQpF,+IAA+I;IAC/I,OAAO,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;CAG1D;AAED,mDAAmD;AACnD,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,UAAU;IAE/C,oGAAoG;IACpG,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,aAAa,CAAC;IAQ7E,oEAAoE;IACpE,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAIpD,+CAA+C;IAC/C,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;CAM/D;AAED,iEAAiE;AACjE,qBAAa,QAAQ;IACP,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,UAAU;IAE/C,8GAA8G;IAC9G,QAAQ,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,cAAc,CAAC;CAOlF"}
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { ApiKeyCreatedSchema, ApiKeyListSchema, ApiKeySchema, RECOMPUTE_QUERY, StorageStatsSchema, TenantStatsSchema, TransferResultSchema, } from "@vol-a/core";
|
|
2
|
+
/** Statistics (scope `files:read`). */
|
|
3
|
+
export class StatsApi {
|
|
4
|
+
client;
|
|
5
|
+
constructor(client) {
|
|
6
|
+
this.client = client;
|
|
7
|
+
}
|
|
8
|
+
/** `GET /stats/tenant[?recompute=1]`: the tenant's live files — count, bytes, per kind, oldest, newest. */
|
|
9
|
+
tenant(options = {}) {
|
|
10
|
+
return this.client.json("/stats/tenant", TenantStatsSchema, {
|
|
11
|
+
query: { [RECOMPUTE_QUERY]: options.recompute },
|
|
12
|
+
signal: options.signal,
|
|
13
|
+
});
|
|
14
|
+
}
|
|
15
|
+
/** `GET /stats/instance/:type/:id[?recompute=1]`: the same for one instance. */
|
|
16
|
+
instance(type, id, options = {}) {
|
|
17
|
+
return this.client.json(`/stats/instance/${encodeURIComponent(type)}/${encodeURIComponent(id)}`, TenantStatsSchema, { query: { [RECOMPUTE_QUERY]: options.recompute }, signal: options.signal });
|
|
18
|
+
}
|
|
19
|
+
/** `GET /stats/storage`: logical bytes and distinct blobs; an admin key also gets `physical` (and, without a tenant, the whole deployment). */
|
|
20
|
+
storage(options = {}) {
|
|
21
|
+
return this.client.json("/stats/storage", StorageStatsSchema, options);
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
/** API keys of the tenant (scope `keys:write`). */
|
|
25
|
+
export class KeysApi {
|
|
26
|
+
client;
|
|
27
|
+
constructor(client) {
|
|
28
|
+
this.client = client;
|
|
29
|
+
}
|
|
30
|
+
/** `POST /keys {name, scopes, env, expires_at?}` → `201`: the key with its plaintext, this once. */
|
|
31
|
+
create(body, options = {}) {
|
|
32
|
+
return this.client.json("/keys", ApiKeyCreatedSchema, {
|
|
33
|
+
method: "POST",
|
|
34
|
+
json: body,
|
|
35
|
+
...options,
|
|
36
|
+
});
|
|
37
|
+
}
|
|
38
|
+
/** `GET /keys`: the tenant's keys, newest first, never the hash. */
|
|
39
|
+
list(options = {}) {
|
|
40
|
+
return this.client.json("/keys", ApiKeyListSchema, options);
|
|
41
|
+
}
|
|
42
|
+
/** `DELETE /keys/:id`: revoke (idempotent). */
|
|
43
|
+
revoke(id, options = {}) {
|
|
44
|
+
return this.client.json(`/keys/${encodeURIComponent(id)}`, ApiKeySchema, {
|
|
45
|
+
method: "DELETE",
|
|
46
|
+
...options,
|
|
47
|
+
});
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
/** Cross-tenant administration (an admin key, scope `admin`). */
|
|
51
|
+
export class AdminApi {
|
|
52
|
+
client;
|
|
53
|
+
constructor(client) {
|
|
54
|
+
this.client = client;
|
|
55
|
+
}
|
|
56
|
+
/** `POST /admin/transfer`: move the files of instances from one tenant to another (`dry_run` counts only). */
|
|
57
|
+
transfer(body, options = {}) {
|
|
58
|
+
return this.client.json("/admin/transfer", TransferResultSchema, {
|
|
59
|
+
method: "POST",
|
|
60
|
+
json: body,
|
|
61
|
+
...options,
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
//# sourceMappingURL=management.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"management.js","sourceRoot":"","sources":["../src/management.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,mBAAmB,EAEnB,gBAAgB,EAChB,YAAY,EACZ,eAAe,EAEf,kBAAkB,EAElB,iBAAiB,EAEjB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAiBrB,uCAAuC;AACvC,MAAM,OAAO,QAAQ;IACU;IAA7B,YAA6B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAEnD,2GAA2G;IAC3G,MAAM,CAAC,UAAwB,EAAE;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,iBAAiB,EAAE;YAC1D,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,SAAS,EAAE;YAC/C,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC;IAED,gFAAgF;IAChF,QAAQ,CAAC,IAAY,EAAE,EAAU,EAAE,UAAwB,EAAE;QAC3D,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CACrB,mBAAmB,kBAAkB,CAAC,IAAI,CAAC,IAAI,kBAAkB,CAAC,EAAE,CAAC,EAAE,EACvE,iBAAiB,EACjB,EAAE,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAC5E,CAAC;IACJ,CAAC;IAED,+IAA+I;IAC/I,OAAO,CAAC,UAAuB,EAAE;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;IACzE,CAAC;CACF;AAED,mDAAmD;AACnD,MAAM,OAAO,OAAO;IACW;IAA7B,YAA6B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAEnD,oGAAoG;IACpG,MAAM,CAAC,IAAkB,EAAE,UAAuB,EAAE;QAClD,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,mBAAmB,EAAE;YACpD,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI;YACV,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED,oEAAoE;IACpE,IAAI,CAAC,UAAuB,EAAE;QAC5B,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,CAAC,CAAC;IAC9D,CAAC;IAED,+CAA+C;IAC/C,MAAM,CAAC,EAAU,EAAE,UAAuB,EAAE;QAC1C,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,YAAY,EAAE;YACvE,MAAM,EAAE,QAAQ;YAChB,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;CACF;AAED,iEAAiE;AACjE,MAAM,OAAO,QAAQ;IACU;IAA7B,YAA6B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAEnD,8GAA8G;IAC9G,QAAQ,CAAC,IAAmB,EAAE,UAAuB,EAAE;QACrD,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE,oBAAoB,EAAE;YAC/D,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI;YACV,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;CACF"}
|
package/dist/shares.d.ts
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import { type ShareCreated, type SharedFolderListing, type ShareInfo, type ShareList } from "@vol-a/core";
|
|
2
|
+
import type { CallOptions, VolaClient } from "./client.js";
|
|
3
|
+
import { type ByteRange } from "./files.js";
|
|
4
|
+
/** `POST /shares` as a caller writes it (the schema's defaults are optional here). */
|
|
5
|
+
export interface ShareCreateInput {
|
|
6
|
+
file_id?: string | undefined;
|
|
7
|
+
folder?: {
|
|
8
|
+
instance_type: string;
|
|
9
|
+
instance_id: string;
|
|
10
|
+
path: string;
|
|
11
|
+
} | undefined;
|
|
12
|
+
scope?: "PUBLIC_LINK" | "TENANT" | "INSTANCE_VIEWERS" | "EMAIL" | undefined;
|
|
13
|
+
password?: string | undefined;
|
|
14
|
+
expires_at?: string | undefined;
|
|
15
|
+
max_downloads?: number | undefined;
|
|
16
|
+
/** A `caller` file only: the grant the caller made (`callerGrant()`). */
|
|
17
|
+
fk_share_ct?: string | undefined;
|
|
18
|
+
}
|
|
19
|
+
export interface ShareListOptions extends CallOptions {
|
|
20
|
+
fileId?: string | undefined;
|
|
21
|
+
folderId?: string | undefined;
|
|
22
|
+
includeRevoked?: boolean | undefined;
|
|
23
|
+
}
|
|
24
|
+
export interface OpenShareOptions {
|
|
25
|
+
/** `fetch` to use (the static `VolaClient.openShare`); default: the global one. */
|
|
26
|
+
fetch?: typeof fetch | undefined;
|
|
27
|
+
/** The password of a protected share (`X-Share-Password`, never the query string). */
|
|
28
|
+
password?: string | undefined;
|
|
29
|
+
range?: ByteRange | undefined;
|
|
30
|
+
/** A file (or subfolder) INSIDE a shared folder, by its path relative to the share. */
|
|
31
|
+
path?: string | undefined;
|
|
32
|
+
method?: "GET" | "HEAD" | undefined;
|
|
33
|
+
/** `?download=1`. */
|
|
34
|
+
download?: boolean | undefined;
|
|
35
|
+
signal?: AbortSignal | undefined;
|
|
36
|
+
}
|
|
37
|
+
/** The share URL without its fragment, and the secret the fragment carried (`null` without one). */
|
|
38
|
+
export declare function parseShareUrl(url: string): {
|
|
39
|
+
url: string;
|
|
40
|
+
secret: string | null;
|
|
41
|
+
};
|
|
42
|
+
/** `openShare` over a given `fetch`: the secret from the fragment as `X-Share-Secret`, the password as a header. */
|
|
43
|
+
export declare function openShareUrl(fetchImpl: typeof fetch, url: string, options?: OpenShareOptions): Promise<Response>;
|
|
44
|
+
export interface CallerGrant {
|
|
45
|
+
/** `fk_share_ct` for `POST /shares`: `nonce ∥ AES-256-GCM(S, FK, "<file id>:key:share:caller")`, base64. */
|
|
46
|
+
fkShareCt: string;
|
|
47
|
+
/** The link secret `S` (32 bytes). Give it to the recipient in the URL fragment ONLY. */
|
|
48
|
+
secret: Uint8Array;
|
|
49
|
+
/** `S` as base64url: what goes after `#` in the share URL. */
|
|
50
|
+
fragment: string;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* The share grant of a `caller`-encrypted file, made by the caller (the server never holds
|
|
54
|
+
* that file's key, so it cannot make one): the file key `fileKey` wrapped under a fresh link
|
|
55
|
+
* secret with the platform's WebCrypto. `fileKey` is the file's FK, which the caller
|
|
56
|
+
* unwrapped from `fk_ct` under its content key (`docs/CRYPTO.md` § 9) — NOT the content key.
|
|
57
|
+
*/
|
|
58
|
+
export declare function callerGrant(fileId: string, fileKey: Uint8Array, secret?: Uint8Array): Promise<CallerGrant>;
|
|
59
|
+
/** Share links: the owner's side (`/shares`, scope `shares:write`) and the recipient's (`/s/<token>`, no key). */
|
|
60
|
+
export declare class SharesApi {
|
|
61
|
+
private readonly client;
|
|
62
|
+
constructor(client: VolaClient);
|
|
63
|
+
/**
|
|
64
|
+
* `POST /shares`: `{file_id}` or `{folder}`, with `password`, `expires_at`, `max_downloads`.
|
|
65
|
+
* Resolves with the info, the `token` (this once) and the public `url` — for an encrypted
|
|
66
|
+
* file (`tenant`, or `keyring` with the owner's unlock) the `url` ends in `#<secret>`: the
|
|
67
|
+
* recipient gets plaintext, and the secret is nowhere but in that link.
|
|
68
|
+
*/
|
|
69
|
+
create(body: ShareCreateInput, options?: CallOptions): Promise<ShareCreated>;
|
|
70
|
+
/** `GET /shares[?file_id=|folder_id=][&include_revoked=1]`, newest first, never the token. */
|
|
71
|
+
list(options?: ShareListOptions): Promise<ShareList>;
|
|
72
|
+
/** `GET /shares/:id`. */
|
|
73
|
+
get(id: string, options?: CallOptions): Promise<ShareInfo>;
|
|
74
|
+
/** `DELETE /shares/:id`: revoke (idempotent); the link answers `410 share_gone` from then on, and a grant is shredded. */
|
|
75
|
+
revoke(id: string, options?: CallOptions): Promise<ShareInfo>;
|
|
76
|
+
/**
|
|
77
|
+
* `POST /shares` for a `caller`-encrypted file: makes the grant (`callerGrant`) and creates
|
|
78
|
+
* the share with it. The `url` returned INCLUDES the `#<secret>` fragment (the server's
|
|
79
|
+
* does not: it never saw the secret). Node only, like everything `caller`.
|
|
80
|
+
*/
|
|
81
|
+
createCallerGrant(fileId: string, fileKey: Uint8Array, body?: Omit<ShareCreateInput, "file_id" | "folder" | "fk_share_ct">, options?: CallOptions): Promise<ShareCreated>;
|
|
82
|
+
/** The recipient's side with this instance's `fetch` (no API key is sent): see `VolaClient.openShare`. */
|
|
83
|
+
open(url: string, options?: Omit<OpenShareOptions, "fetch">): Promise<Response>;
|
|
84
|
+
/** The listing of a shared FOLDER (`GET /s/<token>[/path/<subfolder>]` as JSON). */
|
|
85
|
+
listing(url: string, options?: Omit<OpenShareOptions, "fetch" | "method" | "range">): Promise<SharedFolderListing>;
|
|
86
|
+
}
|
|
87
|
+
//# sourceMappingURL=shares.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"shares.d.ts","sourceRoot":"","sources":["../src/shares.ts"],"names":[],"mappings":"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"}
|
package/dist/shares.js
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
import { CONTENT_KEY_BYTES, callerGrantAad, FORCE_DOWNLOAD_QUERY, INCLUDE_REVOKED_QUERY, SHARE_PASSWORD_HEADER, SHARE_SECRET_BYTES, SHARE_SECRET_HEADER, ShareCreatedSchema, SharedFolderListingSchema, ShareInfoSchema, ShareListSchema, } from "@vol-a/core";
|
|
2
|
+
import { ok2xx } from "./client.js";
|
|
3
|
+
import { bytesToBase64, bytesToBase64Url, encodePath, randomBytes } from "./env.js";
|
|
4
|
+
import { errorFromResponse, VolaError } from "./errors.js";
|
|
5
|
+
import { rangeHeader } from "./files.js";
|
|
6
|
+
/** The share URL without its fragment, and the secret the fragment carried (`null` without one). */
|
|
7
|
+
export function parseShareUrl(url) {
|
|
8
|
+
const parsed = new URL(url);
|
|
9
|
+
const secret = parsed.hash.length > 1 ? parsed.hash.slice(1) : null;
|
|
10
|
+
parsed.hash = "";
|
|
11
|
+
return { url: parsed.toString(), secret };
|
|
12
|
+
}
|
|
13
|
+
/** `openShare` over a given `fetch`: the secret from the fragment as `X-Share-Secret`, the password as a header. */
|
|
14
|
+
export async function openShareUrl(fetchImpl, url, options = {}) {
|
|
15
|
+
const { url: bare, secret } = parseShareUrl(url);
|
|
16
|
+
const target = new URL(bare);
|
|
17
|
+
if (options.path !== undefined) {
|
|
18
|
+
target.pathname = `${target.pathname.replace(/\/+$/, "")}/path/${encodePath(options.path)}`;
|
|
19
|
+
}
|
|
20
|
+
if (options.download)
|
|
21
|
+
target.searchParams.set(FORCE_DOWNLOAD_QUERY, "1");
|
|
22
|
+
const headers = new Headers();
|
|
23
|
+
if (secret)
|
|
24
|
+
headers.set(SHARE_SECRET_HEADER, secret);
|
|
25
|
+
if (options.password !== undefined)
|
|
26
|
+
headers.set(SHARE_PASSWORD_HEADER, options.password);
|
|
27
|
+
if (options.range !== undefined)
|
|
28
|
+
headers.set("range", rangeHeader(options.range));
|
|
29
|
+
const response = await fetchImpl(target.toString(), {
|
|
30
|
+
method: options.method ?? "GET",
|
|
31
|
+
headers,
|
|
32
|
+
...(options.signal ? { signal: options.signal } : {}),
|
|
33
|
+
});
|
|
34
|
+
if (!ok2xx(response.status))
|
|
35
|
+
throw await errorFromResponse(response);
|
|
36
|
+
return response;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* The share grant of a `caller`-encrypted file, made by the caller (the server never holds
|
|
40
|
+
* that file's key, so it cannot make one): the file key `fileKey` wrapped under a fresh link
|
|
41
|
+
* secret with the platform's WebCrypto. `fileKey` is the file's FK, which the caller
|
|
42
|
+
* unwrapped from `fk_ct` under its content key (`docs/CRYPTO.md` § 9) — NOT the content key.
|
|
43
|
+
*/
|
|
44
|
+
export async function callerGrant(fileId, fileKey, secret = randomBytes(SHARE_SECRET_BYTES)) {
|
|
45
|
+
if (fileKey.byteLength !== CONTENT_KEY_BYTES) {
|
|
46
|
+
throw new VolaError({
|
|
47
|
+
status: 0,
|
|
48
|
+
code: "bad_request",
|
|
49
|
+
message: `callerGrant: the file key is ${CONTENT_KEY_BYTES} bytes`,
|
|
50
|
+
});
|
|
51
|
+
}
|
|
52
|
+
if (secret.byteLength !== SHARE_SECRET_BYTES) {
|
|
53
|
+
throw new VolaError({
|
|
54
|
+
status: 0,
|
|
55
|
+
code: "bad_request",
|
|
56
|
+
message: `callerGrant: the secret is ${SHARE_SECRET_BYTES} bytes`,
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
const key = await crypto.subtle.importKey("raw", secret.slice(), "AES-GCM", false, ["encrypt"]);
|
|
60
|
+
const nonce = randomBytes(12);
|
|
61
|
+
const sealed = new Uint8Array(await crypto.subtle.encrypt({
|
|
62
|
+
name: "AES-GCM",
|
|
63
|
+
iv: nonce.slice(),
|
|
64
|
+
additionalData: new TextEncoder().encode(callerGrantAad(fileId)).slice(),
|
|
65
|
+
tagLength: 128,
|
|
66
|
+
}, key, fileKey.slice()));
|
|
67
|
+
const out = new Uint8Array(nonce.length + sealed.length);
|
|
68
|
+
out.set(nonce);
|
|
69
|
+
out.set(sealed, nonce.length);
|
|
70
|
+
return { fkShareCt: bytesToBase64(out), secret, fragment: bytesToBase64Url(secret) };
|
|
71
|
+
}
|
|
72
|
+
/** Share links: the owner's side (`/shares`, scope `shares:write`) and the recipient's (`/s/<token>`, no key). */
|
|
73
|
+
export class SharesApi {
|
|
74
|
+
client;
|
|
75
|
+
constructor(client) {
|
|
76
|
+
this.client = client;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* `POST /shares`: `{file_id}` or `{folder}`, with `password`, `expires_at`, `max_downloads`.
|
|
80
|
+
* Resolves with the info, the `token` (this once) and the public `url` — for an encrypted
|
|
81
|
+
* file (`tenant`, or `keyring` with the owner's unlock) the `url` ends in `#<secret>`: the
|
|
82
|
+
* recipient gets plaintext, and the secret is nowhere but in that link.
|
|
83
|
+
*/
|
|
84
|
+
create(body, options = {}) {
|
|
85
|
+
return this.client.json("/shares", ShareCreatedSchema, {
|
|
86
|
+
method: "POST",
|
|
87
|
+
json: body,
|
|
88
|
+
...options,
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
/** `GET /shares[?file_id=|folder_id=][&include_revoked=1]`, newest first, never the token. */
|
|
92
|
+
list(options = {}) {
|
|
93
|
+
return this.client.json("/shares", ShareListSchema, {
|
|
94
|
+
query: {
|
|
95
|
+
file_id: options.fileId,
|
|
96
|
+
folder_id: options.folderId,
|
|
97
|
+
[INCLUDE_REVOKED_QUERY]: options.includeRevoked,
|
|
98
|
+
},
|
|
99
|
+
signal: options.signal,
|
|
100
|
+
});
|
|
101
|
+
}
|
|
102
|
+
/** `GET /shares/:id`. */
|
|
103
|
+
get(id, options = {}) {
|
|
104
|
+
return this.client.json(`/shares/${encodeURIComponent(id)}`, ShareInfoSchema, options);
|
|
105
|
+
}
|
|
106
|
+
/** `DELETE /shares/:id`: revoke (idempotent); the link answers `410 share_gone` from then on, and a grant is shredded. */
|
|
107
|
+
revoke(id, options = {}) {
|
|
108
|
+
return this.client.json(`/shares/${encodeURIComponent(id)}`, ShareInfoSchema, {
|
|
109
|
+
method: "DELETE",
|
|
110
|
+
...options,
|
|
111
|
+
});
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* `POST /shares` for a `caller`-encrypted file: makes the grant (`callerGrant`) and creates
|
|
115
|
+
* the share with it. The `url` returned INCLUDES the `#<secret>` fragment (the server's
|
|
116
|
+
* does not: it never saw the secret). Node only, like everything `caller`.
|
|
117
|
+
*/
|
|
118
|
+
async createCallerGrant(fileId, fileKey, body = {}, options = {}) {
|
|
119
|
+
const grant = await callerGrant(fileId, fileKey);
|
|
120
|
+
const created = await this.create({ ...body, file_id: fileId, fk_share_ct: grant.fkShareCt }, options);
|
|
121
|
+
return { ...created, url: `${created.url}#${grant.fragment}` };
|
|
122
|
+
}
|
|
123
|
+
/** The recipient's side with this instance's `fetch` (no API key is sent): see `VolaClient.openShare`. */
|
|
124
|
+
open(url, options = {}) {
|
|
125
|
+
return openShareUrl(this.client.rawFetch, url, options);
|
|
126
|
+
}
|
|
127
|
+
/** The listing of a shared FOLDER (`GET /s/<token>[/path/<subfolder>]` as JSON). */
|
|
128
|
+
async listing(url, options = {}) {
|
|
129
|
+
const response = await openShareUrl(this.client.rawFetch, url, { ...options, method: "GET" });
|
|
130
|
+
const body = await response.json();
|
|
131
|
+
if (!(this.client.options.validate ?? false))
|
|
132
|
+
return body;
|
|
133
|
+
const parsed = SharedFolderListingSchema.safeParse(body);
|
|
134
|
+
if (!parsed.success) {
|
|
135
|
+
throw new VolaError({
|
|
136
|
+
status: response.status,
|
|
137
|
+
code: "invalid_response",
|
|
138
|
+
message: `share listing: ${parsed.error.issues[0]?.message ?? "invalid"}`,
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
return parsed.data;
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
//# sourceMappingURL=shares.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"shares.js","sourceRoot":"","sources":["../src/shares.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
import { type ByteSource } from "./body.js";
|
|
2
|
+
import type { CallOptions, VolaClient } from "./client.js";
|
|
3
|
+
import type { UploadPlacement } from "./files.js";
|
|
4
|
+
/** Default chunk of a resumable upload: 8 MiB. */
|
|
5
|
+
export declare const DEFAULT_CHUNK_SIZE: number;
|
|
6
|
+
/**
|
|
7
|
+
* Where a resumable upload remembers which server-side upload a source belongs to, so a
|
|
8
|
+
* second call with the same source continues it: `localStorage` in a browser, memory in
|
|
9
|
+
* Node, or anything with these three methods (a file, a database).
|
|
10
|
+
*/
|
|
11
|
+
export interface FingerprintStore {
|
|
12
|
+
get(key: string): Promise<string | null | undefined> | string | null | undefined;
|
|
13
|
+
set(key: string, value: string): Promise<void> | void;
|
|
14
|
+
remove(key: string): Promise<void> | void;
|
|
15
|
+
}
|
|
16
|
+
export declare class MemoryFingerprintStore implements FingerprintStore {
|
|
17
|
+
private readonly map;
|
|
18
|
+
get(key: string): string | null;
|
|
19
|
+
set(key: string, value: string): void;
|
|
20
|
+
remove(key: string): void;
|
|
21
|
+
}
|
|
22
|
+
/** A `FingerprintStore` over `localStorage` (or any `Storage`). */
|
|
23
|
+
export declare function storageFingerprintStore(storage: Storage): FingerprintStore;
|
|
24
|
+
/** `localStorage` in a browser that has one, the process-wide memory store otherwise. */
|
|
25
|
+
export declare function defaultFingerprintStore(): FingerprintStore;
|
|
26
|
+
export interface UploadProgress {
|
|
27
|
+
/** Bytes the server has (plaintext bytes, also for an encrypted upload). */
|
|
28
|
+
uploaded: number;
|
|
29
|
+
total: number;
|
|
30
|
+
uploadId: string;
|
|
31
|
+
}
|
|
32
|
+
export interface ResumableOptions extends UploadPlacement, CallOptions {
|
|
33
|
+
/** Upsert under a slug once complete. */
|
|
34
|
+
slug?: string | undefined;
|
|
35
|
+
/** Bytes per `PATCH`. Default 8 MiB. */
|
|
36
|
+
chunkSize?: number | undefined;
|
|
37
|
+
onProgress?: ((progress: UploadProgress) => void) | undefined;
|
|
38
|
+
/**
|
|
39
|
+
* The key the upload is remembered under in the `store`, so a later call with the same
|
|
40
|
+
* source resumes it. Default: derived from the base URL, the instance, the name, the size
|
|
41
|
+
* (and a `File`'s `lastModified`). `false`: never remember, never resume.
|
|
42
|
+
*/
|
|
43
|
+
fingerprint?: string | false | undefined;
|
|
44
|
+
/** Where fingerprints live. Default: `localStorage` in a browser, memory in Node. */
|
|
45
|
+
store?: FingerprintStore | undefined;
|
|
46
|
+
}
|
|
47
|
+
export interface ResumableCreate extends UploadPlacement, CallOptions {
|
|
48
|
+
/** The total size, in bytes (the server does not support a deferred length). */
|
|
49
|
+
length: number;
|
|
50
|
+
filename: string;
|
|
51
|
+
slug?: string | undefined;
|
|
52
|
+
}
|
|
53
|
+
export interface UploadState {
|
|
54
|
+
uploadId: string;
|
|
55
|
+
/** Bytes the server has. */
|
|
56
|
+
offset: number;
|
|
57
|
+
length: number;
|
|
58
|
+
/** The `vola_file` id: of the completed file, or — for an encrypted upload — of the file it will become. */
|
|
59
|
+
fileId: string | null;
|
|
60
|
+
/** When the server drops an unfinished upload. */
|
|
61
|
+
expiresAt: string | null;
|
|
62
|
+
/** The upload's metadata as the server keeps it (`instance_type`, `filename`, …); `HEAD` only. */
|
|
63
|
+
metadata: Record<string, string>;
|
|
64
|
+
}
|
|
65
|
+
export interface ResumableResult {
|
|
66
|
+
fileId: string;
|
|
67
|
+
uploadId: string;
|
|
68
|
+
}
|
|
69
|
+
export interface UploadProtocol {
|
|
70
|
+
version: string;
|
|
71
|
+
extensions: string[];
|
|
72
|
+
/** `Tus-Max-Size`: the server's upload limit, in bytes. */
|
|
73
|
+
maxSize: number | null;
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Resumable uploads (`/uploads`, tus 1.0 core + creation/termination/expiration, which the
|
|
77
|
+
* server implements natively). `resumable()` is the whole flow; `create`, `status`, `append`
|
|
78
|
+
* and `abort` are its steps, for a client that drives them itself.
|
|
79
|
+
*/
|
|
80
|
+
export declare class UploadsApi {
|
|
81
|
+
private readonly client;
|
|
82
|
+
constructor(client: VolaClient);
|
|
83
|
+
/** `OPTIONS /uploads`: the protocol version, the extensions, the size limit. No key needed. */
|
|
84
|
+
protocol(options?: CallOptions): Promise<UploadProtocol>;
|
|
85
|
+
/** `POST /uploads`: creates the upload (`201`); the id comes from `Location`. */
|
|
86
|
+
create(type: string, id: string, input: ResumableCreate): Promise<UploadState>;
|
|
87
|
+
/** `HEAD /uploads/:id`: where the upload stands. `404 upload_not_found` / `410` throw. */
|
|
88
|
+
status(uploadId: string, options?: CallOptions): Promise<UploadState>;
|
|
89
|
+
/**
|
|
90
|
+
* `PATCH /uploads/:id`: `chunk` from `offset` on. Resolves with the new offset and, when the
|
|
91
|
+
* upload is complete, the file id. A `keyring` upload needs the unlock token and a `caller`
|
|
92
|
+
* upload the content key on EVERY call (each one unwraps the file key).
|
|
93
|
+
*/
|
|
94
|
+
append(uploadId: string, chunk: Blob | Uint8Array, offset: number, options?: CallOptions): Promise<{
|
|
95
|
+
offset: number;
|
|
96
|
+
fileId: string | null;
|
|
97
|
+
}>;
|
|
98
|
+
/** `DELETE /uploads/:id`: drops the upload and its partial bytes. */
|
|
99
|
+
abort(uploadId: string, options?: CallOptions): Promise<void>;
|
|
100
|
+
/** The default fingerprint of a source. */
|
|
101
|
+
fingerprintOf(type: string, id: string, source: ByteSource, filename: string): string;
|
|
102
|
+
/**
|
|
103
|
+
* The whole resumable flow: remembers the upload under its fingerprint, `HEAD`s a remembered
|
|
104
|
+
* one for its offset (a vanished one is forgotten and started again), creates a new one
|
|
105
|
+
* otherwise, `PATCH`es `chunkSize` bytes at a time from the offset on, reports progress, and
|
|
106
|
+
* resolves with the file id. An abort (`signal`) or a network failure mid-`PATCH` rejects
|
|
107
|
+
* and keeps the fingerprint: the next call with the same source continues where the server
|
|
108
|
+
* stands. A `409` (the server's offset moved) re-reads the offset and goes on.
|
|
109
|
+
*/
|
|
110
|
+
resumable(type: string, id: string, source: ByteSource, options?: ResumableOptions): Promise<ResumableResult>;
|
|
111
|
+
}
|
|
112
|
+
//# sourceMappingURL=uploads.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["../src/uploads.ts"],"names":[],"mappings":"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"}
|