@softure-ai/files 0.0.0-stage → 0.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.
Files changed (156) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/LICENSE +21 -0
  3. package/README.md +213 -2
  4. package/dist/contract.d.ts +51 -0
  5. package/dist/contract.d.ts.map +1 -0
  6. package/dist/contract.js +4 -0
  7. package/dist/contract.js.map +1 -0
  8. package/dist/index.d.ts +45 -0
  9. package/dist/index.d.ts.map +1 -0
  10. package/dist/index.js +49 -0
  11. package/dist/index.js.map +1 -0
  12. package/dist/jobs/index.d.ts +12 -0
  13. package/dist/jobs/index.d.ts.map +1 -0
  14. package/dist/jobs/index.js +22 -0
  15. package/dist/jobs/index.js.map +1 -0
  16. package/dist/messages/en.d.ts +17 -0
  17. package/dist/messages/en.d.ts.map +1 -0
  18. package/dist/messages/en.js +17 -0
  19. package/dist/messages/en.js.map +1 -0
  20. package/dist/messages/index.d.ts +24 -0
  21. package/dist/messages/index.d.ts.map +1 -0
  22. package/dist/messages/index.js +10 -0
  23. package/dist/messages/index.js.map +1 -0
  24. package/dist/next/context.d.ts +4 -0
  25. package/dist/next/context.d.ts.map +1 -0
  26. package/dist/next/context.js +13 -0
  27. package/dist/next/context.js.map +1 -0
  28. package/dist/next/index.d.ts +3 -0
  29. package/dist/next/index.d.ts.map +1 -0
  30. package/dist/next/index.js +5 -0
  31. package/dist/next/index.js.map +1 -0
  32. package/dist/next/route.d.ts +3 -0
  33. package/dist/next/route.d.ts.map +1 -0
  34. package/dist/next/route.js +11 -0
  35. package/dist/next/route.js.map +1 -0
  36. package/dist/options.d.ts +26 -0
  37. package/dist/options.d.ts.map +1 -0
  38. package/dist/options.js +59 -0
  39. package/dist/options.js.map +1 -0
  40. package/dist/schema.d.ts +214 -0
  41. package/dist/schema.d.ts.map +1 -0
  42. package/dist/schema.js +19 -0
  43. package/dist/schema.js.map +1 -0
  44. package/dist/server/context.d.ts +13 -0
  45. package/dist/server/context.d.ts.map +1 -0
  46. package/dist/server/context.js +19 -0
  47. package/dist/server/context.js.map +1 -0
  48. package/dist/server/files.d.ts +48 -0
  49. package/dist/server/files.d.ts.map +1 -0
  50. package/dist/server/files.js +104 -0
  51. package/dist/server/files.js.map +1 -0
  52. package/dist/server/health.d.ts +4 -0
  53. package/dist/server/health.d.ts.map +1 -0
  54. package/dist/server/health.js +20 -0
  55. package/dist/server/health.js.map +1 -0
  56. package/dist/server/index.d.ts +15 -0
  57. package/dist/server/index.d.ts.map +1 -0
  58. package/dist/server/index.js +17 -0
  59. package/dist/server/index.js.map +1 -0
  60. package/dist/server/keys.d.ts +14 -0
  61. package/dist/server/keys.d.ts.map +1 -0
  62. package/dist/server/keys.js +47 -0
  63. package/dist/server/keys.js.map +1 -0
  64. package/dist/server/links.d.ts +30 -0
  65. package/dist/server/links.d.ts.map +1 -0
  66. package/dist/server/links.js +122 -0
  67. package/dist/server/links.js.map +1 -0
  68. package/dist/server/local-storage.d.ts +7 -0
  69. package/dist/server/local-storage.d.ts.map +1 -0
  70. package/dist/server/local-storage.js +83 -0
  71. package/dist/server/local-storage.js.map +1 -0
  72. package/dist/server/names.d.ts +11 -0
  73. package/dist/server/names.d.ts.map +1 -0
  74. package/dist/server/names.js +32 -0
  75. package/dist/server/names.js.map +1 -0
  76. package/dist/server/options.d.ts +8 -0
  77. package/dist/server/options.d.ts.map +1 -0
  78. package/dist/server/options.js +31 -0
  79. package/dist/server/options.js.map +1 -0
  80. package/dist/server/privacy.d.ts +16 -0
  81. package/dist/server/privacy.d.ts.map +1 -0
  82. package/dist/server/privacy.js +39 -0
  83. package/dist/server/privacy.js.map +1 -0
  84. package/dist/server/prune.d.ts +13 -0
  85. package/dist/server/prune.d.ts.map +1 -0
  86. package/dist/server/prune.js +34 -0
  87. package/dist/server/prune.js.map +1 -0
  88. package/dist/server/queries.d.ts +7 -0
  89. package/dist/server/queries.d.ts.map +1 -0
  90. package/dist/server/queries.js +17 -0
  91. package/dist/server/queries.js.map +1 -0
  92. package/dist/server/s3-storage.d.ts +33 -0
  93. package/dist/server/s3-storage.d.ts.map +1 -0
  94. package/dist/server/s3-storage.js +223 -0
  95. package/dist/server/s3-storage.js.map +1 -0
  96. package/dist/server/save.d.ts +29 -0
  97. package/dist/server/save.d.ts.map +1 -0
  98. package/dist/server/save.js +141 -0
  99. package/dist/server/save.js.map +1 -0
  100. package/dist/server/serve.d.ts +11 -0
  101. package/dist/server/serve.d.ts.map +1 -0
  102. package/dist/server/serve.js +108 -0
  103. package/dist/server/serve.js.map +1 -0
  104. package/dist/server/sigv4.d.ts +23 -0
  105. package/dist/server/sigv4.d.ts.map +1 -0
  106. package/dist/server/sigv4.js +57 -0
  107. package/dist/server/sigv4.js.map +1 -0
  108. package/dist/storage.d.ts +32 -0
  109. package/dist/storage.d.ts.map +1 -0
  110. package/dist/storage.js +10 -0
  111. package/dist/storage.js.map +1 -0
  112. package/dist/testing/index.d.ts +3 -0
  113. package/dist/testing/index.d.ts.map +1 -0
  114. package/dist/testing/index.js +4 -0
  115. package/dist/testing/index.js.map +1 -0
  116. package/dist/testing/links.d.ts +22 -0
  117. package/dist/testing/links.d.ts.map +1 -0
  118. package/dist/testing/links.js +30 -0
  119. package/dist/testing/links.js.map +1 -0
  120. package/dist/testing/memory-storage.d.ts +11 -0
  121. package/dist/testing/memory-storage.d.ts.map +1 -0
  122. package/dist/testing/memory-storage.js +52 -0
  123. package/dist/testing/memory-storage.js.map +1 -0
  124. package/migrations/0001_create_files.sql +32 -0
  125. package/module.json +24 -0
  126. package/package.json +72 -4
  127. package/src/contract.ts +59 -0
  128. package/src/index.ts +53 -0
  129. package/src/jobs/index.ts +23 -0
  130. package/src/messages/en.ts +16 -0
  131. package/src/messages/index.ts +13 -0
  132. package/src/next/context.ts +14 -0
  133. package/src/next/index.ts +4 -0
  134. package/src/next/route.ts +11 -0
  135. package/src/options.ts +64 -0
  136. package/src/schema.ts +22 -0
  137. package/src/server/context.ts +32 -0
  138. package/src/server/files.ts +133 -0
  139. package/src/server/health.ts +20 -0
  140. package/src/server/index.ts +45 -0
  141. package/src/server/keys.ts +56 -0
  142. package/src/server/links.ts +152 -0
  143. package/src/server/local-storage.ts +87 -0
  144. package/src/server/names.ts +35 -0
  145. package/src/server/options.ts +34 -0
  146. package/src/server/privacy.ts +53 -0
  147. package/src/server/prune.ts +46 -0
  148. package/src/server/queries.ts +19 -0
  149. package/src/server/s3-storage.ts +255 -0
  150. package/src/server/save.ts +167 -0
  151. package/src/server/serve.ts +106 -0
  152. package/src/server/sigv4.ts +82 -0
  153. package/src/storage.ts +43 -0
  154. package/src/testing/index.ts +3 -0
  155. package/src/testing/links.ts +47 -0
  156. package/src/testing/memory-storage.ts +64 -0
@@ -0,0 +1,23 @@
1
+ export declare const EMPTY_PAYLOAD_SHA256: string;
2
+ export interface SigV4Credentials {
3
+ readonly accessKeyId: string;
4
+ readonly secretAccessKey: string;
5
+ }
6
+ export interface SignRequestInput {
7
+ readonly method: string;
8
+ /** The URL as sent: its path already percent-encoded per segment (`encodeRfc3986`), its query in any order. */
9
+ readonly url: URL;
10
+ /** Headers to sign besides `host`, `x-amz-date` and `x-amz-content-sha256`, which the signer sets. */
11
+ readonly headers?: Readonly<Record<string, string>>;
12
+ /** Lowercase hex SHA-256 of the body (`EMPTY_PAYLOAD_SHA256` for none). */
13
+ readonly payloadSha256: string;
14
+ readonly region: string;
15
+ readonly service?: string;
16
+ readonly credentials: SigV4Credentials;
17
+ readonly date: Date;
18
+ }
19
+ /** RFC 3986 percent-encoding as SigV4 wants it: everything but `A-Z a-z 0-9 - . _ ~` is escaped. */
20
+ export declare function encodeRfc3986(value: string): string;
21
+ /** The request's headers with `authorization` added: every header in the result is signed. */
22
+ export declare function signRequest(input: SignRequestInput): Record<string, string>;
23
+ //# sourceMappingURL=sigv4.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sigv4.d.ts","sourceRoot":"","sources":["../../src/server/sigv4.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,oBAAoB,QAAgD,CAAC;AAElF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+GAA+G;IAC/G,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,sGAAsG;IACtG,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED,oGAAoG;AACpG,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAkBD,8FAA8F;AAC9F,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0B3E"}
@@ -0,0 +1,57 @@
1
+ // AWS Signature Version 4 for S3-compatible storage (R2, MinIO, Garage, AWS), with `node:crypto` only. The signer
2
+ // takes the request as it will be sent and answers the headers to add; it is checked against the test vector AWS
3
+ // publishes for S3 (tests/sigv4.test.ts).
4
+ import { createHash, createHmac } from "node:crypto";
5
+ const ALGORITHM = "AWS4-HMAC-SHA256";
6
+ export const EMPTY_PAYLOAD_SHA256 = createHash("sha256").update("").digest("hex");
7
+ /** RFC 3986 percent-encoding as SigV4 wants it: everything but `A-Z a-z 0-9 - . _ ~` is escaped. */
8
+ export function encodeRfc3986(value) {
9
+ return encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
10
+ }
11
+ function sha256Hex(value) {
12
+ return createHash("sha256").update(value, "utf8").digest("hex");
13
+ }
14
+ function hmac(key, value) {
15
+ return createHmac("sha256", key).update(value, "utf8").digest();
16
+ }
17
+ /** `20130524T000000Z`. */
18
+ function formatAmzDate(date) {
19
+ return date
20
+ .toISOString()
21
+ .replace(/[-:]/g, "")
22
+ .replace(/\.\d{3}/, "");
23
+ }
24
+ /** The request's headers with `authorization` added: every header in the result is signed. */
25
+ export function signRequest(input) {
26
+ const service = input.service ?? "s3";
27
+ const amzDate = formatAmzDate(input.date);
28
+ const day = amzDate.slice(0, 8);
29
+ const headers = {};
30
+ for (const [name, value] of Object.entries(input.headers ?? {}))
31
+ headers[name.toLowerCase()] = value;
32
+ headers.host = input.url.host;
33
+ headers["x-amz-content-sha256"] = input.payloadSha256;
34
+ headers["x-amz-date"] = amzDate;
35
+ const names = Object.keys(headers).sort();
36
+ const canonicalHeaders = names.map((name) => `${name}:${(headers[name] ?? "").trim().replace(/\s+/g, " ")}\n`).join("");
37
+ const signedHeaders = names.join(";");
38
+ const canonicalQuery = [...input.url.searchParams.entries()]
39
+ .map(([name, value]) => [encodeRfc3986(name), encodeRfc3986(value)])
40
+ .sort(([a, aValue], [b, bValue]) => (a === b ? compare(aValue, bValue) : compare(a, b)))
41
+ .map(([name, value]) => `${name}=${value}`)
42
+ .join("&");
43
+ const canonicalRequest = [input.method, input.url.pathname, canonicalQuery, canonicalHeaders, signedHeaders, input.payloadSha256].join("\n");
44
+ const scope = `${day}/${input.region}/${service}/aws4_request`;
45
+ const stringToSign = [ALGORITHM, amzDate, scope, sha256Hex(canonicalRequest)].join("\n");
46
+ const signingKey = hmac(hmac(hmac(hmac(`AWS4${input.credentials.secretAccessKey}`, day), input.region), service), "aws4_request");
47
+ const signature = createHmac("sha256", signingKey).update(stringToSign, "utf8").digest("hex");
48
+ headers.authorization = `${ALGORITHM} Credential=${input.credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
49
+ return headers;
50
+ }
51
+ /** Byte order, as SigV4 sorts (not the locale's). */
52
+ function compare(a, b) {
53
+ if (a === b)
54
+ return 0;
55
+ return a < b ? -1 : 1;
56
+ }
57
+ //# sourceMappingURL=sigv4.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sigv4.js","sourceRoot":"","sources":["../../src/server/sigv4.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,32 @@
1
+ import type { ByteRange } from "./contract.js";
2
+ /** A file's bytes as a driver receives them: a Node stream, a web stream or any async iterable of chunks. */
3
+ export type FileBody = AsyncIterable<Uint8Array>;
4
+ /** What a driver's health probe found. */
5
+ export interface StorageCheck {
6
+ /** A probe object could be written and deleted. */
7
+ readonly isWritable: boolean;
8
+ /** The free bytes where the files live, or null when the driver cannot tell (object storage). */
9
+ readonly freeBytes: number | null;
10
+ }
11
+ export interface FileStorage {
12
+ /** A short name for logs and the README (`local`, `s3`, `memory`). */
13
+ readonly kind: string;
14
+ /**
15
+ * Stores `body` under `key`, replacing nothing visible until the whole body is written: a body that throws half
16
+ * way leaves no object behind and the error propagates.
17
+ */
18
+ put(body: FileBody, key: string): Promise<void>;
19
+ /** The object's bytes, or the inclusive `range` of them; null when there is no such object. */
20
+ get(key: string, range?: ByteRange): Promise<ReadableStream<Uint8Array> | null>;
21
+ /** The object's size, or null when there is no such object. */
22
+ head(key: string): Promise<{
23
+ readonly size: number;
24
+ } | null>;
25
+ /** Deletes the object; deleting a missing one is not an error. */
26
+ delete(key: string): Promise<void>;
27
+ /** Probes the storage for the health check; a driver without one counts as healthy. */
28
+ check?(): Promise<StorageCheck>;
29
+ }
30
+ /** Whether a value has the driver methods (the options schema's check). */
31
+ export declare function isFileStorage(value: unknown): value is FileStorage;
32
+ //# sourceMappingURL=storage.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,6GAA6G;AAC7G,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;AAEjD,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,iGAAiG;IACjG,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,+FAA+F;IAC/F,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;IAChF,+DAA+D;IAC/D,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAC7D,kEAAkE;IAClE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,uFAAuF;IACvF,KAAK,CAAC,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;CACjC;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAQlE"}
@@ -0,0 +1,10 @@
1
+ /** Whether a value has the driver methods (the options schema's check). */
2
+ export function isFileStorage(value) {
3
+ if (typeof value !== "object" || value === null)
4
+ return false;
5
+ const candidate = value;
6
+ return (typeof candidate.kind === "string" &&
7
+ ["put", "get", "head", "delete"].every((name) => typeof candidate[name] === "function") &&
8
+ (candidate.check === undefined || typeof candidate.check === "function"));
9
+ }
10
+ //# sourceMappingURL=storage.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAiCA,2EAA2E;AAC3E,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,SAAS,GAAG,KAAgC,CAAC;IACnD,OAAO,CACL,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ;QAClC,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,SAAS,CAAC,IAAI,CAAC,KAAK,UAAU,CAAC;QACvF,CAAC,SAAS,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,SAAS,CAAC,KAAK,KAAK,UAAU,CAAC,CACzE,CAAC;AACJ,CAAC"}
@@ -0,0 +1,3 @@
1
+ export { createMemoryStorage, type MemoryStorage } from "./memory-storage.js";
2
+ export { createTestLinkKeys, fetchFileLink, readFileLinkExpiry, type FetchFileLinkOptions, type FileLinkAnswer } from "./links.js";
3
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC"}
@@ -0,0 +1,4 @@
1
+ // Test helpers of @softure-ai/files: an in-memory storage driver, a fixed link keyring and link checks.
2
+ export { createMemoryStorage } from "./memory-storage.js";
3
+ export { createTestLinkKeys, fetchFileLink, readFileLinkExpiry } from "./links.js";
4
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,wGAAwG;AACxG,OAAO,EAAE,mBAAmB,EAAsB,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,kBAAkB,EAAkD,MAAM,YAAY,CAAC"}
@@ -0,0 +1,22 @@
1
+ import type { FilesContext } from "../server/context.js";
2
+ /**
3
+ * An environment with a link keyring of the given key ids (first one signs), each key derived from its id, so two
4
+ * calls agree: `env: createTestLinkKeys(["new", "old"])`. Never for production.
5
+ */
6
+ export declare function createTestLinkKeys(ids?: readonly string[]): Readonly<Record<string, string>>;
7
+ export interface FetchFileLinkOptions {
8
+ readonly method?: "GET" | "HEAD";
9
+ /** A `Range` header value, e.g. `bytes=0-99`. */
10
+ readonly range?: string;
11
+ }
12
+ /** What a link answered, with the body read. */
13
+ export interface FileLinkAnswer {
14
+ readonly status: number;
15
+ readonly headers: Readonly<Record<string, string>>;
16
+ readonly body: Uint8Array;
17
+ }
18
+ /** Requests a link (a URL or a path) as the route would serve it, at the context's clock. */
19
+ export declare function fetchFileLink(ctx: FilesContext, link: string, options?: FetchFileLinkOptions): Promise<FileLinkAnswer>;
20
+ /** The expiry a link carries in its path (it may still die earlier: revoked, deleted). */
21
+ export declare function readFileLinkExpiry(link: string): Date;
22
+ //# sourceMappingURL=links.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../src/testing/links.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAIzD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,SAAS,MAAM,EAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAGtG;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACjC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED,6FAA6F;AAC7F,wBAAsB,aAAa,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,cAAc,CAAC,CAShI;AAED,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAKrD"}
@@ -0,0 +1,30 @@
1
+ import { FILES_LINK_KEYS_ENV } from "../server/keys.js";
2
+ import { serveFileLink } from "../server/serve.js";
3
+ /**
4
+ * An environment with a link keyring of the given key ids (first one signs), each key derived from its id, so two
5
+ * calls agree: `env: createTestLinkKeys(["new", "old"])`. Never for production.
6
+ */
7
+ export function createTestLinkKeys(ids = ["test"]) {
8
+ const entries = ids.map((id) => `${id}:${Buffer.alloc(32, `softure-files-test-${id}`).toString("base64url")}`);
9
+ return { [FILES_LINK_KEYS_ENV]: entries.join(",") };
10
+ }
11
+ /** Requests a link (a URL or a path) as the route would serve it, at the context's clock. */
12
+ export async function fetchFileLink(ctx, link, options = {}) {
13
+ const url = new URL(link, ctx.config.appOrigin);
14
+ const headers = options.range === undefined ? {} : { range: options.range };
15
+ const response = await serveFileLink(ctx, new Request(url, { method: options.method ?? "GET", headers }));
16
+ return {
17
+ status: response.status,
18
+ headers: Object.fromEntries(response.headers.entries()),
19
+ body: new Uint8Array(await response.arrayBuffer()),
20
+ };
21
+ }
22
+ /** The expiry a link carries in its path (it may still die earlier: revoked, deleted). */
23
+ export function readFileLinkExpiry(link) {
24
+ const segments = new URL(link, "http://localhost").pathname.split("/");
25
+ const expiry = segments.at(-3);
26
+ if (expiry === undefined || !/^\d+$/.test(expiry))
27
+ throw new RangeError("readFileLinkExpiry: not a file link");
28
+ return new Date(Number(expiry) * 1000);
29
+ }
30
+ //# sourceMappingURL=links.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"links.js","sourceRoot":"","sources":["../../src/testing/links.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAyB,CAAC,MAAM,CAAC;IAClE,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,sBAAsB,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAC/G,OAAO,EAAE,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACtD,CAAC;AAeD,6FAA6F;AAC7F,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAiB,EAAE,IAAY,EAAE,UAAgC,EAAE;IACrG,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,OAAO,GAA2B,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;IACpG,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IAC1G,OAAO;QACL,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACvD,IAAI,EAAE,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC;KACnD,CAAC;AACJ,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACvE,MAAM,MAAM,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,qCAAqC,CAAC,CAAC;IAC/G,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;AACzC,CAAC"}
@@ -0,0 +1,11 @@
1
+ import type { FileStorage, StorageCheck } from "../storage.js";
2
+ export interface MemoryStorage extends FileStorage {
3
+ /** The stored objects by key (a copy). */
4
+ readonly objects: () => ReadonlyMap<string, Uint8Array>;
5
+ /** What `check()` answers; healthy with plenty of space by default. */
6
+ setCheck(check: StorageCheck): void;
7
+ /** Makes `put` (after reading the whole body) and `delete` throw until called with false. */
8
+ setFailing(isFailing: boolean): void;
9
+ }
10
+ export declare function createMemoryStorage(): MemoryStorage;
11
+ //# sourceMappingURL=memory-storage.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"memory-storage.d.ts","sourceRoot":"","sources":["../../src/testing/memory-storage.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAY,WAAW,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEzE,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxD,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACpC,6FAA6F;IAC7F,UAAU,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;CACtC;AAED,wBAAgB,mBAAmB,IAAI,aAAa,CAiDnD"}
@@ -0,0 +1,52 @@
1
+ export function createMemoryStorage() {
2
+ const objects = new Map();
3
+ let health = {
4
+ isWritable: true,
5
+ freeBytes: Number.MAX_SAFE_INTEGER,
6
+ };
7
+ let isFailing = false;
8
+ return {
9
+ kind: "memory",
10
+ objects: () => new Map(objects),
11
+ setCheck(check) {
12
+ health = check;
13
+ },
14
+ setFailing(value) {
15
+ isFailing = value;
16
+ },
17
+ async put(body, key) {
18
+ const chunks = [];
19
+ for await (const chunk of body)
20
+ chunks.push(chunk);
21
+ if (isFailing)
22
+ throw new Error("memory storage: put failed (setFailing)");
23
+ objects.set(key, Buffer.concat(chunks));
24
+ },
25
+ get(key, range) {
26
+ const bytes = objects.get(key);
27
+ if (bytes === undefined)
28
+ return Promise.resolve(null);
29
+ const slice = range === undefined ? bytes : bytes.subarray(range.start, range.end + 1);
30
+ return Promise.resolve(new ReadableStream({
31
+ start(controller) {
32
+ controller.enqueue(new Uint8Array(slice));
33
+ controller.close();
34
+ },
35
+ }));
36
+ },
37
+ head(key) {
38
+ const bytes = objects.get(key);
39
+ return Promise.resolve(bytes === undefined ? null : { size: bytes.byteLength });
40
+ },
41
+ delete(key) {
42
+ if (isFailing)
43
+ return Promise.reject(new Error("memory storage: delete failed (setFailing)"));
44
+ objects.delete(key);
45
+ return Promise.resolve();
46
+ },
47
+ check() {
48
+ return Promise.resolve(health);
49
+ },
50
+ };
51
+ }
52
+ //# sourceMappingURL=memory-storage.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"memory-storage.js","sourceRoot":"","sources":["../../src/testing/memory-storage.ts"],"names":[],"mappings":"AAcA,MAAM,UAAU,mBAAmB;IACjC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC9C,IAAI,MAAM,GAAiB;QACzB,UAAU,EAAE,IAAI;QAChB,SAAS,EAAE,MAAM,CAAC,gBAAgB;KACnC,CAAC;IACF,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC;QAC/B,QAAQ,CAAC,KAAK;YACZ,MAAM,GAAG,KAAK,CAAC;QACjB,CAAC;QACD,UAAU,CAAC,KAAK;YACd,SAAS,GAAG,KAAK,CAAC;QACpB,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,IAAc,EAAE,GAAW;YACnC,MAAM,MAAM,GAAiB,EAAE,CAAC;YAChC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI;gBAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnD,IAAI,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;YAC1E,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QAC1C,CAAC;QACD,GAAG,CAAC,GAAW,EAAE,KAAiB;YAChC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACtD,MAAM,KAAK,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;YACvF,OAAO,OAAO,CAAC,OAAO,CACpB,IAAI,cAAc,CAAa;gBAC7B,KAAK,CAAC,UAAU;oBACd,UAAU,CAAC,OAAO,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;oBAC1C,UAAU,CAAC,KAAK,EAAE,CAAC;gBACrB,CAAC;aACF,CAAC,CACH,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAW;YACd,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;QAClF,CAAC;QACD,MAAM,CAAC,GAAW;YAChB,IAAI,SAAS;gBAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC,CAAC;YAC9F,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,KAAK;YACH,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;KACF,CAAC;AACJ,CAAC"}
@@ -0,0 +1,32 @@
1
+ -- The app's stored files: one row per file, its bytes in the configured storage under `storage_key`. A deleted or
2
+ -- expired file keeps its row until `pruneFiles` has removed its bytes, so nothing is left behind in storage.
3
+ -- Rollback: DROP TABLE files.files; then DELETE FROM softure.migrations WHERE module = 'files' AND version = 1;
4
+ -- (the objects in storage are not touched by a rollback).
5
+ CREATE TABLE files (
6
+ id uuid PRIMARY KEY,
7
+ -- The account the file belongs to. No foreign key: the module works with any account store.
8
+ owner_id text NOT NULL CHECK (char_length(owner_id) BETWEEN 1 AND 200),
9
+ sha256 text NOT NULL CHECK (sha256 ~ '^[0-9a-f]{64}$'),
10
+ size bigint NOT NULL CHECK (size >= 0),
11
+ -- A media type with optional parameters, printable ASCII only (it is sent back as a header).
12
+ content_type text NOT NULL CHECK (content_type ~ '^[a-z0-9][a-z0-9!#$&^_.+-]*/[a-z0-9][a-z0-9!#$&^_.+-]*(;[ -~]*)?$' AND char_length(content_type) <= 255),
13
+ -- The sanitised name: no slash, backslash or control character.
14
+ original_name text NOT NULL CHECK (char_length(original_name) BETWEEN 1 AND 255 AND original_name !~ '[/\\[:cntrl:]]'),
15
+ kind text NOT NULL CHECK (kind ~ '^[a-z][a-z0-9_-]{0,31}$'),
16
+ storage_key text NOT NULL CHECK (storage_key ~ '^[a-z0-9][a-z0-9/-]{0,199}$'),
17
+ -- Bumped by revokeFileLinks: a link signed for an older generation stops working.
18
+ link_generation integer NOT NULL DEFAULT 1 CHECK (link_generation >= 1),
19
+ expires_at timestamptz,
20
+ deleted_at timestamptz,
21
+ created_at timestamptz NOT NULL,
22
+ CONSTRAINT files_storage_key_key UNIQUE (storage_key),
23
+ CONSTRAINT files_expiry_check CHECK (expires_at IS NULL OR expires_at > created_at)
24
+ );
25
+
26
+ -- An owner's live files, newest first (listFiles, the quota sum, the privacy export).
27
+ CREATE INDEX files_owner_created_idx ON files (owner_id, created_at DESC) WHERE deleted_at IS NULL;
28
+ -- Dedupe: an owner's live file with a given hash.
29
+ CREATE INDEX files_owner_sha256_idx ON files (owner_id, sha256) WHERE deleted_at IS NULL;
30
+ -- Prune: files whose time is up, and files deleted but not yet removed from storage.
31
+ CREATE INDEX files_expires_at_idx ON files (expires_at) WHERE expires_at IS NOT NULL;
32
+ CREATE INDEX files_deleted_at_idx ON files (deleted_at) WHERE deleted_at IS NOT NULL;
package/module.json ADDED
@@ -0,0 +1,24 @@
1
+ {
2
+ "id": "files",
3
+ "version": "0.1.1",
4
+ "dependsOn": { "jobs": "^0.1.6?" },
5
+ "dbSchema": "files",
6
+ "tables": ["files"],
7
+ "env": [
8
+ {
9
+ "name": "SOFTURE_FILES_LINK_KEYS",
10
+ "required": false,
11
+ "description": "Signing keyring for public file links: <id>:<base64 32 bytes>[,<id>:<key>...], the first one signs; needed only by createFileLink and the link route"
12
+ }
13
+ ],
14
+ "switches": [],
15
+ "routes": { "links": "/f" },
16
+ "mount": [
17
+ {
18
+ "kind": "route-handler",
19
+ "path": "app/f/[...link]/route.ts",
20
+ "export": "serveFileLinkRoute"
21
+ }
22
+ ],
23
+ "privacy": { "exports": true, "deletes": true }
24
+ }
package/package.json CHANGED
@@ -1,6 +1,74 @@
1
1
  {
2
2
  "name": "@softure-ai/files",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "SOFTURE AI files module: an app's stored files (content hash, size, type, owner, kind, expiry, a per-owner quota, opt-in dedupe) on a storage driver (local disk with atomic writes, S3-compatible with SigV4 and multipart uploads, in memory for tests), streamed and never buffered, public links that expire (HMAC-signed, checked before any database read, revocable per file, a rotating keyring) served by a Next.js route with byte ranges and one 404 for every dead link, a prune job, a privacy contributor and a health check.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "sideEffects": false,
8
+ "engines": {
9
+ "node": ">=22"
10
+ },
11
+ "repository": {
12
+ "type": "git",
13
+ "url": "git+https://github.com/SOFTURE/AI.git",
14
+ "directory": "modules/files"
15
+ },
16
+ "files": [
17
+ "dist",
18
+ "CHANGELOG.md",
19
+ "src",
20
+ "!src/**/*.test.ts",
21
+ "!src/**/*.test.tsx",
22
+ "migrations",
23
+ "module.json"
24
+ ],
25
+ "publishConfig": {
26
+ "access": "public",
27
+ "provenance": true
28
+ },
29
+ "exports": {
30
+ ".": {
31
+ "@softure-ai/source": "./src/index.ts",
32
+ "types": "./dist/index.d.ts",
33
+ "default": "./dist/index.js"
34
+ },
35
+ "./server": {
36
+ "@softure-ai/source": "./src/server/index.ts",
37
+ "types": "./dist/server/index.d.ts",
38
+ "default": "./dist/server/index.js"
39
+ },
40
+ "./next": {
41
+ "@softure-ai/source": "./src/next/index.ts",
42
+ "types": "./dist/next/index.d.ts",
43
+ "default": "./dist/next/index.js"
44
+ },
45
+ "./jobs": {
46
+ "@softure-ai/source": "./src/jobs/index.ts",
47
+ "types": "./dist/jobs/index.d.ts",
48
+ "default": "./dist/jobs/index.js"
49
+ },
50
+ "./testing": {
51
+ "@softure-ai/source": "./src/testing/index.ts",
52
+ "types": "./dist/testing/index.d.ts",
53
+ "default": "./dist/testing/index.js"
54
+ }
55
+ },
56
+ "scripts": {
57
+ "build": "tsc -p tsconfig.build.json"
58
+ },
59
+ "dependencies": {
60
+ "@softure-ai/core": "^0.2.7",
61
+ "@softure-ai/db": "^0.1.14",
62
+ "zod": "^4.6.5"
63
+ },
64
+ "peerDependencies": {
65
+ "@softure-ai/jobs": "^0.1.6",
66
+ "drizzle-orm": "^0.45.2",
67
+ "next": "^16.0.0"
68
+ },
69
+ "peerDependenciesMeta": {
70
+ "@softure-ai/jobs": {
71
+ "optional": true
72
+ }
73
+ }
74
+ }
@@ -0,0 +1,59 @@
1
+ // Result types and error codes of the files module. No user-facing copy here: an app translates codes through
2
+ // `messages` (docs/02-module-standard.md §6).
3
+
4
+ /** The link keyring cannot sign: a configuration problem, never fixed by retrying. */
5
+ export type FilesKeyErrorCode =
6
+ /** `SOFTURE_FILES_LINK_KEYS` is not set. */
7
+ | "files.link_key_missing"
8
+ /** `SOFTURE_FILES_LINK_KEYS` is set but is not a list of `<id>:<base64 32 bytes>`. */
9
+ | "files.link_key_invalid";
10
+
11
+ /** Why `saveFile` refused a file. */
12
+ export type FilesSaveErrorCode =
13
+ /** The input breaks a rule: an empty owner, a malformed kind or content type, an expiry in the past. */
14
+ | "files.invalid_input"
15
+ /** The file is larger than `maxFileBytes`. */
16
+ | "files.too_large"
17
+ /** Saving it would take the owner above `quotaBytesPerOwner`. */
18
+ | "files.quota_exceeded";
19
+
20
+ /** Why a file could not be read, deleted or linked. */
21
+ export type FilesLookupErrorCode =
22
+ /** No live file has this id (unknown, another owner's, deleted or expired). */
23
+ | "files.not_found"
24
+ /** The asked range starts at or after the end of the file. */
25
+ | "files.range_not_satisfiable";
26
+
27
+ export type FilesErrorCode = FilesKeyErrorCode | FilesSaveErrorCode | FilesLookupErrorCode;
28
+
29
+ /** A stored file as the app sees it. Never carries the storage key. */
30
+ export interface StoredFile {
31
+ readonly id: string;
32
+ /** The account the file belongs to (an auth user id, or any id the app keeps). */
33
+ readonly ownerId: string;
34
+ /** Lowercase hex SHA-256 of the content. */
35
+ readonly sha256: string;
36
+ readonly size: number;
37
+ readonly contentType: string;
38
+ /** The name it was saved under, sanitised: no folders, no control characters, at most 255 characters. */
39
+ readonly name: string;
40
+ /** The app's own category (`input`, `output`, `export`). */
41
+ readonly kind: string;
42
+ readonly expiresAt: Date | null;
43
+ readonly createdAt: Date;
44
+ }
45
+
46
+ /** An inclusive byte range, both ends within the file. */
47
+ export interface ByteRange {
48
+ readonly start: number;
49
+ readonly end: number;
50
+ }
51
+
52
+ /** A public link to a file. */
53
+ export interface FileLink {
54
+ /** The absolute URL on the app's origin. */
55
+ readonly url: string;
56
+ /** The path part, `/f/<id>/<expiry>/<signature>/<name>`. */
57
+ readonly path: string;
58
+ readonly expiresAt: Date;
59
+ }
package/src/index.ts ADDED
@@ -0,0 +1,53 @@
1
+ // Public API of @softure-ai/files: the module factory for softure.config.ts, its types, messages and table. The
2
+ // storage drivers and every database function are in `@softure-ai/files/server`, the link route in `/next`, the
3
+ // prune job in `/jobs` and the test helpers (an in-memory driver, link checks) in `/testing`.
4
+ import { defineModule, resolveMigrationsDir } from "@softure-ai/core";
5
+ import { filesMessages } from "./messages/index.js";
6
+ import { filesOptionsSchema } from "./options.js";
7
+ import { checkFilesHealth } from "./server/health.js";
8
+ import { filesPrivacyContributor } from "./server/privacy.js";
9
+
10
+ export const MODULE_ID = "files";
11
+
12
+ /**
13
+ * Enables stored files in `softure.config.ts`:
14
+ * `files({ storage: createLocalStorage({ dir: "/data/files" }), quotaBytesPerOwner: 2 * 1024 ** 3 })`.
15
+ */
16
+ export const files = defineModule({
17
+ manifest: {
18
+ id: MODULE_ID,
19
+ version: "0.1.1",
20
+ dependsOn: { jobs: "^0.1.6?" },
21
+ dbSchema: "files",
22
+ tables: ["files"],
23
+ env: [
24
+ {
25
+ name: "SOFTURE_FILES_LINK_KEYS",
26
+ required: false,
27
+ description:
28
+ "Signing keyring for public file links: <id>:<base64 32 bytes>[,<id>:<key>...], the first one signs; needed only by createFileLink and the link route",
29
+ },
30
+ ],
31
+ switches: [],
32
+ routes: { links: "/f" },
33
+ mount: [
34
+ {
35
+ kind: "route-handler",
36
+ path: "app/f/[...link]/route.ts",
37
+ export: "serveFileLinkRoute",
38
+ },
39
+ ],
40
+ privacy: { exports: true, deletes: true },
41
+ },
42
+ messages: filesMessages,
43
+ options: filesOptionsSchema,
44
+ migrations: { dir: resolveMigrationsDir(import.meta.url, "../migrations/") },
45
+ privacy: filesPrivacyContributor,
46
+ health: checkFilesHealth,
47
+ });
48
+
49
+ export type { ByteRange, FileLink, FilesErrorCode, FilesKeyErrorCode, FilesLookupErrorCode, FilesSaveErrorCode, StoredFile } from "./contract.js";
50
+ export { filesMessages, getFilesErrorMessage, type FilesMessages } from "./messages/index.js";
51
+ export { DEFAULT_FILE_KIND, FILE_KIND_PATTERN, type FilesOptions, type FilesOptionsInput } from "./options.js";
52
+ export { files as filesTable } from "./schema.js";
53
+ export { isFileStorage, type FileBody, type FileStorage, type StorageCheck } from "./storage.js";
@@ -0,0 +1,23 @@
1
+ // The jobs adapter of @softure-ai/files: the prune as a `@softure-ai/jobs` handler and schedule (an optional peer
2
+ // dependency; only apps that import this entry need it).
3
+ import { ok } from "@softure-ai/core";
4
+ import { defineJobHandler, type JobHandlers, type JobSchedulesInput } from "@softure-ai/jobs";
5
+ import { z } from "zod";
6
+ import { pruneFiles } from "../server/prune.js";
7
+
8
+ /** Handlers for the worker: `handlers: { ...filesJobHandlers }`. */
9
+ export const filesJobHandlers = {
10
+ /** Removes expired and deleted files from storage and the table (`pruneFiles`). */
11
+ "files.prune": defineJobHandler({
12
+ payload: z.object({}),
13
+ run: async (_payload, ctx) => {
14
+ await pruneFiles(ctx);
15
+ return ok();
16
+ },
17
+ }),
18
+ } satisfies JobHandlers;
19
+
20
+ /** Schedules for `jobs({ schedules: { ...filesJobSchedules } })`: hourly. */
21
+ export const filesJobSchedules = {
22
+ "files.prune": { every: "1h" },
23
+ } satisfies JobSchedulesInput;
@@ -0,0 +1,16 @@
1
+ export const en = {
2
+ errors: {
3
+ files: {
4
+ link_key_missing: "Links cannot be made: the link signing key is not configured.",
5
+ link_key_invalid: "Links cannot be made: the link signing key is malformed.",
6
+ invalid_input: "The file details are not valid.",
7
+ too_large: "The file is too large.",
8
+ quota_exceeded: "There is no space left for this file.",
9
+ not_found: "The file was not found.",
10
+ range_not_satisfiable: "The requested part of the file is outside it.",
11
+ },
12
+ core: {
13
+ unexpected: "Something went wrong. Try again.",
14
+ },
15
+ },
16
+ };
@@ -0,0 +1,13 @@
1
+ import { en } from "./en.js";
2
+
3
+ /** The built-in English dictionary; an app passes partial overrides or its own translation per locale. */
4
+ export const filesMessages = { en };
5
+
6
+ export type FilesMessages = typeof en;
7
+
8
+ /** The copy for an error code (`files.*`); an unknown code gets the generic failure. */
9
+ export function getFilesErrorMessage(messages: FilesMessages, code: string): string {
10
+ const name = code.startsWith("files.") ? code.slice("files.".length) : "";
11
+ const group: Readonly<Record<string, string>> = messages.errors.files;
12
+ return (Object.hasOwn(group, name) ? group[name] : undefined) ?? messages.errors.core.unexpected;
13
+ }
@@ -0,0 +1,14 @@
1
+ // What the adapter hands the server functions: the registered config, the process-wide database handle and the
2
+ // wall clock. The link keyring comes from `process.env`.
3
+ import { systemClock, type SoftureConfig } from "@softure-ai/core";
4
+ import { getSoftureConfig } from "@softure-ai/core/next";
5
+ import { getConfiguredDatabase } from "@softure-ai/db";
6
+ import type { FilesContext } from "../server/context.js";
7
+
8
+ export async function getFilesContext(config: SoftureConfig = getSoftureConfig()): Promise<FilesContext> {
9
+ if (config.database === null) {
10
+ throw new Error("@softure-ai/files: softure.config.ts has no database; files needs one");
11
+ }
12
+ const { db } = await getConfiguredDatabase(config.database);
13
+ return { db, clock: systemClock, config };
14
+ }
@@ -0,0 +1,4 @@
1
+ // The Next.js adapter of @softure-ai/files: the public link route and the request-side context
2
+ // (docs/02-module-standard.md §8).
3
+ export { getFilesContext } from "./context.js";
4
+ export { serveFileLinkRoute } from "./route.js";