@stacksjs/storage 0.70.44 → 0.70.53

package/dist/src/signed-url.d.ts

@@ -8,6 +8,38 @@ import type { SignedUrlOptions } from './types';
  * ```
  */
 export declare function createSignedStorageToken(path: string, options: SignedUrlOptions): string;
+/**
+ * Revoke a signed storage token so subsequent
+ * {@link verifySignedStorageToken} calls return
+ * `{ valid: false, reason: 'revoked' }`. Idempotent — calling
+ * twice is a no-op.
+ *
+ * Pass either the full JWS compact-form token or just the signature
+ * segment (the part after the second `.`); both work because
+ * verification keys off the signature segment.
+ *
+ * @example
+ * ```ts
+ * const url = await Storage.disk('local').signedUrl('reports/q4.pdf', { expiresIn: 3600 })
+ * // ... url is shared, then later leaked
+ * revokeSignedStorageToken(extractTokenFromUrl(url))
+ * // Any further fetch with that URL → 403
+ * ```
+ */
+export declare function revokeSignedStorageToken(token: string): void;
+/**
+ * Check whether a signature has been revoked. Exposed for tests
+ * and for distributed-cache replicators that need to peek at the
+ * set; production callers should rely on {@link verifySignedStorageToken}
+ * to consult this automatically.
+ */
+export declare function isSignedStorageTokenRevoked(sigPart: string): boolean;
+/**
+ * Test-only: clear the revocation set. The set is process-local
+ * and unbounded across tests would let one test's revoke bleed
+ * into another's verification.
+ */
+export declare function clearRevokedSignedStorageTokens(): void;
 /**
  * Verify a signed storage token. The caller MUST pass the requested
  * path so we can ensure the token's `path` claim matches what the
@@ -32,6 +64,6 @@ declare interface SignedTokenClaims {
  */
 export declare interface SignedTokenVerification {
   valid: boolean
-  reason?: 'malformed' | 'bad_signature' | 'expired' | 'path_mismatch'
+  reason?: 'malformed' | 'bad_signature' | 'expired' | 'path_mismatch' | 'revoked'
   claims?: SignedTokenClaims
 }

package/dist/src/types/filesystem.d.ts

@@ -42,6 +42,28 @@ export declare interface S3DiskConfig extends BaseDiskConfig {
     secret: string
   }
 }
+/**
+ * Userland-augmentable disk-name registry (stacksjs/stacks#1924).
+ *
+ * Empty by default — the framework can't know an app's configured
+ * disks at its own build time. Apps declare their disks once and get
+ * autocomplete on `Storage.disk('…')` everywhere:
+ *
+ * ```ts
+ * // types/storage.d.ts
+ * declare module '@stacksjs/storage' {
+ *   interface KnownDisks {
+ *     local: true
+ *     public: true
+ *     s3: true
+ *   }
+ * }
+ * ```
+ *
+ * Mirrors the `DatabaseSchema` pattern from stacksjs/stacks#1923.
+ */
+// eslint-disable-next-line ts/no-empty-object-type
+export declare interface KnownDisks {}
 /**
  * Main filesystem configuration
  *
@@ -98,3 +120,12 @@ export type Visibility = 'public' | 'private';
  * Union type for all disk configurations
  */
 export type DiskConfig = LocalDiskConfig | S3DiskConfig;
+/**
+ * A configured disk name (autocompletes to the keys of an augmented
+ * {@link KnownDisks}) or any other string. The `(string & {})` branch
+ * keeps the union from collapsing back to `string`, so known disks
+ * surface in autocomplete while arbitrary names still type-check —
+ * apps that haven't augmented `KnownDisks` keep compiling unchanged.
+ */
+// eslint-disable-next-line ts/no-empty-object-type
+export type DiskName = (keyof KnownDisks & string) | (string & {});

package/dist/src/types.d.ts

@@ -32,6 +32,45 @@ export declare interface StatEntry {
   mimeType?: string
   metadata?: Record<string, any>
 }
+/**
+ * Options for `Storage.getStream(path, options?)`
+ * (stacksjs/stacks#1886).
+ */
+export declare interface GetStreamOptions {
+  signal?: AbortSignal
+}
+/**
+ * Options for `Storage.putStream(path, stream, options?)`
+ * (stacksjs/stacks#1886). All fields are optional; the S3 driver
+ * reads them to tune its multipart pipeline, other drivers
+ * generally only honor `contentType` and `signal`.
+ */
+export declare interface PutStreamOptions {
+  contentType?: string
+  signal?: AbortSignal
+  partSize?: number
+  concurrency?: number
+  maxRetries?: number
+}
+/**
+ * Result returned from `Storage.put()` (stacksjs/stacks#1888 S-8).
+ *
+ * Pre-fix `put()` returned `Promise<void>` — callers that wanted to
+ * record an etag for cache-invalidation or a size for storage-quota
+ * accounting had to issue a second `.stat()` round-trip. This shape
+ * carries the metadata back from the write itself.
+ *
+ * Fields beyond `path` are best-effort: drivers that don't expose
+ * (or can't cheaply compute) a value omit it rather than synthesizing
+ * a fake one. Callers should treat them as nullable.
+ */
+export declare interface PutResult {
+  path: string
+  size: number
+  contentType?: string
+  lastModified?: number
+  etag?: string
+}
 /**
  * Directory listing entry
  */
@@ -75,6 +114,51 @@ export declare interface SignedUrlOptions {
   issuer?: string
   baseUrl?: string
 }
+/**
+ * Options for `presignedUploadPolicy()` — the POST-form upload
+ * primitive that S3 can enforce server-side (stacksjs/stacks#1888
+ * Phase B). Distinct from {@link PresignedUploadUrlOptions} (PUT-
+ * form): the POST policy carries a `Content-Length-Range` condition
+ * that S3 enforces server-side, so this is the right primitive when
+ * you genuinely need a size cap against an untrusted client.
+ */
+export declare interface PresignedUploadPolicyOptions {
+  key: string | { startsWith: string }
+  contentType: string | { startsWith: string }
+  contentLengthRange?: { min: number, max: number }
+  acl?: 'private' | 'public-read' | 'public-read-write' | 'authenticated-read' | 'bucket-owner-read' | 'bucket-owner-full-control'
+  expiresIn: number
+  fields?: Record<string, string>
+}
+/**
+ * What the caller hands to the browser. Submit as
+ * `multipart/form-data` to `url` with every entry of `fields` as a
+ * form field, then the actual file LAST under the field name
+ * `'file'`. `key` is what the upload will land at — store on the
+ * domain record.
+ */
+export declare interface PresignedUploadPolicy {
+  url: string
+  fields: Record<string, string>
+  key: string
+}
+/**
+ * Options for `presignedUploadUrl()` (stacksjs/stacks#1856 Stage 6).
+ */
+export declare interface PresignedUploadUrlOptions {
+  contentType: string
+  expiresIn: number
+  dir?: string
+  filename?: string
+  maxBytes?: number
+}
+export declare interface PresignedUploadUrl {
+  url: string
+  path: string
+  key: string
+  contentType: string
+  maxBytes?: number
+}
 /**
  * Checksum algorithm options
  */
@@ -98,13 +182,14 @@ export declare interface StorageAdapterConfig {
   credentials?: {
     accessKeyId: string
     secretAccessKey: string
+    sessionToken?: string
   }
 }
 /**
  * Base storage adapter interface
  */
 export declare interface StorageAdapter {
-  write(path: string, contents: FileContents): Promise<void>
+  write(path: string, contents: FileContents): Promise<PutResult>
   read(path: string): Promise<FileContents>
   readToString(path: string): Promise<string>
   readToBuffer(path: string): Promise<Buffer>
@@ -123,6 +208,10 @@ export declare interface StorageAdapter {
   publicUrl(path: string, options?: PublicUrlOptions): Promise<string>
   temporaryUrl(path: string, options: TemporaryUrlOptions): Promise<string>
   signedUrl?(path: string, options: SignedUrlOptions): Promise<string>
+  presignedUploadUrl?(options: PresignedUploadUrlOptions): Promise<PresignedUploadUrl>
+  presignedUploadPolicy?(options: PresignedUploadPolicyOptions): Promise<PresignedUploadPolicy>
+  getStream?(path: string, options?: GetStreamOptions): Promise<ReadableStream<Uint8Array>>
+  putStream?(path: string, stream: ReadableStream<Uint8Array>, options?: PutStreamOptions): Promise<PutResult>
   checksum(path: string, options?: ChecksumOptions): Promise<string>
   mimeType(path: string, options?: MimeTypeOptions): Promise<string>
   lastModified(path: string): Promise<number>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/storage",
   "type": "module",
-  "version": "0.70.44",
+  "version": "0.70.53",
   "description": "The Stacks file system.",
   "author": "Chris Breuer",
   "contributors": [
@@ -51,14 +51,14 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/ts-cloud": "^0.2.15"
+    "@stacksjs/ts-cloud": "^0.7.12"
   },
   "devDependencies": {
-    "@stacksjs/arrays": "^0.70.44",
+    "@stacksjs/arrays": "0.70.53",
     "better-dx": "^0.2.12",
-    "@stacksjs/error-handling": "^0.70.44",
-    "@stacksjs/path": "^0.70.44",
-    "@stacksjs/strings": "^0.70.44",
-    "@stacksjs/types": "^0.70.44"
+    "@stacksjs/error-handling": "0.70.53",
+    "@stacksjs/path": "0.70.53",
+    "@stacksjs/strings": "0.70.53",
+    "@stacksjs/types": "0.70.53"
   }
 }