@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/app/services/storage/S3StorageAdapter.js

@@ -0,0 +1,162 @@
+import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { BadRequestError } from "../../../http/errors/BadRequestError.js";
+/**
+ * Default upper bound on `signedUrl` TTL in seconds. 24 hours — long
+ * enough for typical share-link UX, short enough that a leaked URL is
+ * a bounded, auditable window rather than an indefinite back door.
+ * Override per-adapter via `S3StorageAdapterOptions.maxExpiresInSec`.
+ */
+const DEFAULT_MAX_EXPIRES_IN_SEC = 86_400;
+export class S3StorageAdapter {
+    client;
+    bucket;
+    keyPrefix;
+    maxExpiresInSec;
+    constructor(opts) {
+        this.client = opts.client;
+        this.bucket = opts.bucket;
+        this.keyPrefix = opts.keyPrefix ?? "";
+        this.maxExpiresInSec = opts.maxExpiresInSec ?? DEFAULT_MAX_EXPIRES_IN_SEC;
+        if (this.maxExpiresInSec <= 0) {
+            throw new Error(`S3StorageAdapter: maxExpiresInSec must be positive (got ${this.maxExpiresInSec})`);
+        }
+    }
+    k(key) {
+        return this.keyPrefix + key;
+    }
+    /** Strip the prefix from a key returned by the SDK so callers see what they asked for. */
+    unk(awsKey) {
+        return awsKey.startsWith(this.keyPrefix) ? awsKey.slice(this.keyPrefix.length) : awsKey;
+    }
+    async bodyToS3(body) {
+        if (Buffer.isBuffer(body))
+            return body;
+        if (body instanceof Uint8Array)
+            return body;
+        if (body instanceof Blob)
+            return new Uint8Array(await body.arrayBuffer());
+        if (typeof body.getReader === "function") {
+            const reader = body.getReader();
+            const chunks = [];
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (value)
+                    chunks.push(value);
+            }
+            return Buffer.concat(chunks);
+        }
+        throw new Error("S3StorageAdapter: unsupported body type");
+    }
+    async put(key, body, opts = {}) {
+        const buf = await this.bodyToS3(body);
+        const command = new PutObjectCommand({
+            Bucket: this.bucket,
+            Key: this.k(key),
+            Body: buf,
+            ContentType: opts.contentType,
+            CacheControl: opts.cacheControl,
+            Metadata: opts.metadata,
+        });
+        const response = await this.client.send(command);
+        return {
+            key,
+            size: buf.byteLength,
+            contentType: opts.contentType,
+            etag: response.ETag,
+            metadata: opts.metadata,
+        };
+    }
+    async get(key) {
+        try {
+            const response = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: this.k(key) }));
+            const body = response.Body;
+            if (!body)
+                return null;
+            // The SDK exposes Body as a `Readable | ReadableStream | Blob`
+            // depending on runtime; transformToWebStream() unifies it.
+            const stream = typeof body.transformToWebStream === "function"
+                ? body.transformToWebStream()
+                : body;
+            const meta = {
+                key,
+                size: response.ContentLength ?? 0,
+                contentType: response.ContentType,
+                lastModified: response.LastModified,
+                etag: response.ETag,
+                metadata: response.Metadata,
+            };
+            return { stream, meta };
+        }
+        catch (err) {
+            if (isS3NotFound(err))
+                return null;
+            throw err;
+        }
+    }
+    async exists(key) {
+        try {
+            await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: this.k(key) }));
+            return true;
+        }
+        catch (err) {
+            if (isS3NotFound(err))
+                return false;
+            throw err;
+        }
+    }
+    async delete(key) {
+        await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: this.k(key) }));
+    }
+    async list(prefix = "", opts = {}) {
+        const response = await this.client.send(new ListObjectsV2Command({
+            Bucket: this.bucket,
+            Prefix: this.k(prefix),
+            MaxKeys: opts.maxKeys ?? 1000,
+            ContinuationToken: opts.continuationToken,
+        }));
+        const objects = (response.Contents ?? []).map((entry) => ({
+            key: this.unk(entry.Key ?? ""),
+            size: entry.Size ?? 0,
+            lastModified: entry.LastModified,
+            etag: entry.ETag,
+        }));
+        return {
+            objects,
+            nextContinuationToken: response.IsTruncated ? response.NextContinuationToken : undefined,
+        };
+    }
+    async signedUrl(key, opts = {}) {
+        const expiresIn = opts.expiresInSec ?? 900;
+        if (expiresIn <= 0 || expiresIn > this.maxExpiresInSec) {
+            throw new BadRequestError(`Signed URL TTL out of range: ${expiresIn}s (must be > 0 and <= ${this.maxExpiresInSec}s)`);
+        }
+        const method = opts.method ?? "GET";
+        if (method === "PUT") {
+            const command = new PutObjectCommand({
+                Bucket: this.bucket,
+                Key: this.k(key),
+                ContentType: opts.contentType,
+            });
+            return getSignedUrl(this.client, command, { expiresIn });
+        }
+        const command = new GetObjectCommand({ Bucket: this.bucket, Key: this.k(key) });
+        return getSignedUrl(this.client, command, { expiresIn });
+    }
+}
+/** Detect "key not found" across the SDK's error variants. */
+function isS3NotFound(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const e = err;
+    if (e.name === "NoSuchKey" || e.name === "NotFound")
+        return true;
+    if (e.Code === "NoSuchKey" || e.Code === "NotFound")
+        return true;
+    if (e.$metadata?.httpStatusCode === 404)
+        return true;
+    return false;
+}
+//# sourceMappingURL=S3StorageAdapter.js.map

package/lib/app/services/storage/S3StorageAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"S3StorageAdapter.js","sourceRoot":"","sources":["../../../../src/app/services/storage/S3StorageAdapter.ts"],"names":[],"mappings":"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"}

package/lib/app/services/storage/StorageService.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `StorageService` — framework-wide blob/object storage abstraction.
+ *
+ * Three adapters ship in v4.0:
+ *   - `DiskStorageAdapter` (this batch) — local filesystem; tests + dev.
+ *   - `S3StorageAdapter` (next batch) — `@aws-sdk/client-s3` as optional
+ *     peer dep; production default for AWS.
+ *   - `GCSStorageAdapter` (next batch) — `@google-cloud/storage` as
+ *     optional peer dep; Sixth Summit's GCP default.
+ *
+ * The interface is intentionally narrow — `put` / `get` / `exists` /
+ * `delete` / `list` / `signedUrl` — so future adapters (R2, Azure Blob,
+ * Cloudflare KV-as-blob) can plug in without API churn. Per-adapter
+ * options that don't fit the common shape go in the constructor, not the
+ * interface.
+ */
+export type StorageBody = Buffer | Uint8Array | ReadableStream | Blob | File;
+export interface StorageObjectMeta {
+    /** Object key relative to the adapter's namespace (no leading "/"). */
+    key: string;
+    /** Size in bytes. */
+    size: number;
+    /** MIME type if recorded. */
+    contentType?: string;
+    /** Last-modified timestamp if the adapter reports it. */
+    lastModified?: Date;
+    /** Adapter-specific entity tag (md5, opaque, etc.). */
+    etag?: string;
+    /** User-supplied metadata recorded at put-time. */
+    metadata?: Record<string, string>;
+}
+export interface PutOptions {
+    contentType?: string;
+    cacheControl?: string;
+    metadata?: Record<string, string>;
+}
+export interface ListOptions {
+    /** Max objects per page. Default 1000. */
+    maxKeys?: number;
+    /** Opaque cursor returned by the previous page. */
+    continuationToken?: string;
+}
+export interface ListResult {
+    objects: StorageObjectMeta[];
+    nextContinuationToken?: string;
+}
+export interface SignedUrlOptions {
+    /**
+     * TTL in seconds. Default 900 (15 min). Bounded by the adapter's
+     * `maxExpiresInSec` (default 86400 = 24h); values exceeding the
+     * ceiling throw `BadRequestError`.
+     *
+     * The ceiling defends multi-tenant deployments: a long-lived
+     * signed URL survives session revocation, role changes, and tenant
+     * migrations, so any leak (logs, share-link UX, analytics, browser
+     * history forwarded to support) becomes a window of cross-tenant
+     * data exposure with no audit trail. Per-adapter configurable when
+     * a higher ceiling is genuinely required.
+     */
+    expiresInSec?: number;
+    /** `"GET"` (download) or `"PUT"` (browser-direct upload). Default `"GET"`. */
+    method?: "GET" | "PUT";
+    /** Required `Content-Type` for PUT pre-signed URLs. */
+    contentType?: string;
+}
+export interface GetResult {
+    /** Streaming body. The caller must drain or cancel. */
+    stream: ReadableStream;
+    meta: StorageObjectMeta;
+}
+export interface StorageService {
+    /** Upload `body` under `key`. Returns the recorded metadata. */
+    put(key: string, body: StorageBody, opts?: PutOptions): Promise<StorageObjectMeta>;
+    /** Returns `null` when the object doesn't exist. */
+    get(key: string): Promise<GetResult | null>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, opts?: ListOptions): Promise<ListResult>;
+    /**
+     * Pre-signed URL for direct browser GET / PUT. Optional — adapters that
+     * can't sign (e.g., the disk adapter without a separate file server)
+     * should throw a clear error. Consumers that need signed URLs can branch
+     * on `if ("signedUrl" in service)` or assume the production adapter
+     * always implements it.
+     */
+    signedUrl?(key: string, opts?: SignedUrlOptions): Promise<string>;
+}
+//# sourceMappingURL=StorageService.d.ts.map

package/lib/app/services/storage/StorageService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageService.d.ts","sourceRoot":"","sources":["../../../../src/app/services/storage/StorageService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,cAAc,GAAG,IAAI,GAAG,IAAI,CAAC;AAE7E,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,YAAY,CAAC,EAAE,IAAI,CAAC;IACpB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACvB,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,uDAAuD;IACvD,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEnF,oDAAoD;IACpD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAE5C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAE/D;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACnE"}

package/lib/app/services/storage/StorageService.js

@@ -0,0 +1,18 @@
+/**
+ * `StorageService` — framework-wide blob/object storage abstraction.
+ *
+ * Three adapters ship in v4.0:
+ *   - `DiskStorageAdapter` (this batch) — local filesystem; tests + dev.
+ *   - `S3StorageAdapter` (next batch) — `@aws-sdk/client-s3` as optional
+ *     peer dep; production default for AWS.
+ *   - `GCSStorageAdapter` (next batch) — `@google-cloud/storage` as
+ *     optional peer dep; Sixth Summit's GCP default.
+ *
+ * The interface is intentionally narrow — `put` / `get` / `exists` /
+ * `delete` / `list` / `signedUrl` — so future adapters (R2, Azure Blob,
+ * Cloudflare KV-as-blob) can plug in without API churn. Per-adapter
+ * options that don't fit the common shape go in the constructor, not the
+ * interface.
+ */
+export {};
+//# sourceMappingURL=StorageService.js.map

package/lib/app/services/storage/StorageService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageService.js","sourceRoot":"","sources":["../../../../src/app/services/storage/StorageService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/lib/app/services/storage/index.d.ts

@@ -0,0 +1,5 @@
+export { DiskStorageAdapter, type DiskStorageAdapterOptions } from "./DiskStorageAdapter.js";
+export { GCSStorageAdapter, type GCSStorageAdapterOptions } from "./GCSStorageAdapter.js";
+export { S3StorageAdapter, type S3StorageAdapterOptions } from "./S3StorageAdapter.js";
+export type { GetResult, ListOptions, ListResult, PutOptions, SignedUrlOptions, StorageBody, StorageObjectMeta, StorageService, } from "./StorageService.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/app/services/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/app/services/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAC7F,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAE1F,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACvF,YAAY,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,cAAc,GACf,MAAM,qBAAqB,CAAC"}

package/lib/app/services/storage/index.js

@@ -0,0 +1,4 @@
+export { DiskStorageAdapter } from "./DiskStorageAdapter.js";
+export { GCSStorageAdapter } from "./GCSStorageAdapter.js";
+export { S3StorageAdapter } from "./S3StorageAdapter.js";
+//# sourceMappingURL=index.js.map

package/lib/app/services/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/app/services/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAkC,MAAM,yBAAyB,CAAC;AAC7F,OAAO,EAAE,iBAAiB,EAAiC,MAAM,wBAAwB,CAAC;AAE1F,OAAO,EAAE,gBAAgB,EAAgC,MAAM,uBAAuB,CAAC"}

package/lib/app/utils/ContextValidators.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Context validators for common data access patterns
+ */
+export declare class ContextValidators {
+    /**
+     * Validates that the user can only access their own data
+     */
+    static ownData(req: any, entity: any): boolean;
+    /**
+     * Validates that the user can access data they created
+     */
+    static ownCreatedData(req: any, entity: any): boolean;
+    /**
+     * Validates that the user can access data in their organization/group
+     */
+    static sameOrganization(req: any, entity: any): boolean;
+    /**
+     * Validates that the user can access data they have a relationship with
+     */
+    static hasRelationship(req: any, entity: any, relationshipField: string): boolean;
+    /**
+     * Validates that the user can access data based on a custom field comparison
+     */
+    static customField(req: any, entity: any, fieldPath: string): boolean;
+    /**
+     * Validates that the user can access data based on multiple conditions (AND logic)
+     */
+    static and(...validators: Array<(req: any, entity: any) => boolean>): (req: any, entity: any) => boolean;
+    /**
+     * Validates that the user can access data based on multiple conditions (OR logic)
+     */
+    static or(...validators: Array<(req: any, entity: any) => boolean>): (req: any, entity: any) => boolean;
+    /**
+     * Validates that the user has admin privileges (bypasses context checks)
+     */
+    static adminBypass(req: any, entity: any): boolean;
+    /**
+     * Validates that the user can access data based on a custom function
+     */
+    static custom(validator: (req: any, entity: any) => boolean): (req: any, entity: any) => boolean;
+    /**
+     * Helper to get nested object values using dot notation
+     */
+    private static getNestedValue;
+}
+//# sourceMappingURL=ContextValidators.d.ts.map

package/lib/app/utils/ContextValidators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextValidators.d.ts","sourceRoot":"","sources":["../../../src/app/utils/ContextValidators.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,iBAAiB;IAC5B;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO;IAK9C;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO;IAKrD;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO;IAKvD;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,EAAE,MAAM,GAAG,OAAO;IAKjF;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAOrE;;OAEG;IACH,MAAM,CAAC,GAAG,CACR,GAAG,UAAU,EAAE,KAAK,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,GACvD,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,OAAO;IAMrC;;OAEG;IACH,MAAM,CAAC,EAAE,CACP,GAAG,UAAU,EAAE,KAAK,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,GACvD,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,OAAO;IAMrC;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO;IAIlD;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,OAAO,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,OAAO;IAIhG;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;CAG9B"}

package/lib/app/utils/ContextValidators.js

@@ -0,0 +1,81 @@
+/**
+ * Context validators for common data access patterns
+ */
+export class ContextValidators {
+    /**
+     * Validates that the user can only access their own data
+     */
+    static ownData(req, entity) {
+        if (!req.user || !entity)
+            return false;
+        return req.user.id === entity.accountId || req.user.id === entity.userId;
+    }
+    /**
+     * Validates that the user can access data they created
+     */
+    static ownCreatedData(req, entity) {
+        if (!req.user || !entity)
+            return false;
+        return req.user.id === entity.createdById || req.user.id === entity.authorId;
+    }
+    /**
+     * Validates that the user can access data in their organization/group
+     */
+    static sameOrganization(req, entity) {
+        if (!req.user || !entity)
+            return false;
+        return req.user.organizationId === entity.organizationId || req.user.groupId === entity.groupId;
+    }
+    /**
+     * Validates that the user can access data they have a relationship with
+     */
+    static hasRelationship(req, entity, relationshipField) {
+        if (!req.user || !entity)
+            return false;
+        return req.user.id === entity[relationshipField];
+    }
+    /**
+     * Validates that the user can access data based on a custom field comparison
+     */
+    static customField(req, entity, fieldPath) {
+        if (!req.user || !entity)
+            return false;
+        const fieldValue = ContextValidators.getNestedValue(entity, fieldPath);
+        return req.user.id === fieldValue;
+    }
+    /**
+     * Validates that the user can access data based on multiple conditions (AND logic)
+     */
+    static and(...validators) {
+        return (req, entity) => {
+            return validators.every((validator) => validator(req, entity));
+        };
+    }
+    /**
+     * Validates that the user can access data based on multiple conditions (OR logic)
+     */
+    static or(...validators) {
+        return (req, entity) => {
+            return validators.some((validator) => validator(req, entity));
+        };
+    }
+    /**
+     * Validates that the user has admin privileges (bypasses context checks)
+     */
+    static adminBypass(req, entity) {
+        return req.user?.hasPermission("admin") || req.user?.hasPermission("superuser");
+    }
+    /**
+     * Validates that the user can access data based on a custom function
+     */
+    static custom(validator) {
+        return validator;
+    }
+    /**
+     * Helper to get nested object values using dot notation
+     */
+    static getNestedValue(obj, path) {
+        return path.split(".").reduce((current, key) => current?.[key], obj);
+    }
+}
+//# sourceMappingURL=ContextValidators.js.map

package/lib/app/utils/ContextValidators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextValidators.js","sourceRoot":"","sources":["../../../src/app/utils/ContextValidators.ts"],"names":[],"mappings":"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"}

package/lib/app/utils/defineEnv.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `defineEnv` — boot-time environment validation.
+ *
+ * Accepts any schema with a `safeParse(data) -> { success, data | error }` shape
+ * (Zod 3, Zod 4, Valibot adapter, etc.) so the framework stays validator-agnostic
+ * at the type level. On failure: prints a structured "missing/invalid: VAR (type)"
+ * report and exits with code 1 *before* the app boots.
+ *
+ * Replaces the v3 pattern of scattered `process.env.FOO || ""` reads with a single
+ * typed env object. Eliminates the class of "mystery runtime errors from a typo'd
+ * env var" by failing loudly at startup.
+ */
+export interface EnvSchemaIssue {
+    path: ReadonlyArray<PropertyKey>;
+    message: string;
+    code?: string;
+}
+export interface EnvSchemaError {
+    issues: ReadonlyArray<EnvSchemaIssue>;
+}
+export type EnvSafeParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: EnvSchemaError;
+};
+export interface EnvSchema<T> {
+    safeParse(data: unknown): EnvSafeParseResult<T>;
+}
+export interface DefineEnvOptions {
+    /** Source of env vars. Defaults to `process.env`. */
+    source?: NodeJS.ProcessEnv;
+    /**
+     * Override the failure handler. Default logs a report and calls `process.exit(1)`.
+     * Useful in tests so a bad fixture doesn't kill the test runner.
+     */
+    onFailure?: (issues: ReadonlyArray<EnvSchemaIssue>) => never;
+    /**
+     * Logger for the failure report. Defaults to `console.error`.
+     * In v4 this will default to the framework's pino logger.
+     */
+    logger?: Pick<Console, "error">;
+}
+/**
+ * Replace common secret-value shapes with `<redacted>` before logging.
+ *
+ * Framework-default Zod messages don't include the raw value (e.g.
+ * "String must contain at least 32 character(s)"), but consumer
+ * schemas using `.refine((v) => …, { message: `got "${v}"` })` or
+ * transform-based validators that include the raw value will spill
+ * the secret through this `console.error` path — observability
+ * stacks (Stackdriver, Datadog, Loki) capture stdout/stderr by
+ * default, and the secret then becomes searchable, indexed, and
+ * forwarded across systems. A regex scrub here is the last line of
+ * defense before that boundary.
+ *
+ * The patterns are intentionally narrow (named token shapes) plus
+ * one generic-high-entropy catch-all. False positives are limited
+ * to error messages that happen to contain ≥32 contiguous
+ * base64-alphabet characters with no separators — rare in legit
+ * Zod messages.
+ */
+export declare function scrubSecrets(message: string): string;
+/**
+ * Validate process.env against a schema. Returns the typed env on success;
+ * exits the process with a structured error report on failure.
+ *
+ * @example
+ *   import { z } from "zod";
+ *   const schema = z.object({
+ *     PORT: z.coerce.number().int().positive().default(3000),
+ *     DATABASE_URL: z.string().url(),
+ *     SESSION_SECRET: z.string().min(32),
+ *   });
+ *   export const env = defineEnv(schema);
+ *   // env.PORT is typed as number, env.DATABASE_URL as string, etc.
+ */
+export declare function defineEnv<T>(schema: EnvSchema<T>, opts?: DefineEnvOptions): T;
+//# sourceMappingURL=defineEnv.d.ts.map

package/lib/app/utils/defineEnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineEnv.d.ts","sourceRoot":"","sources":["../../../src/app/utils/defineEnv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,cAAc;IAM7B,IAAI,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CACvC;AAED,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAC5B;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAC1B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC;AAE9C,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,KAAK,KAAK,CAAC;IAC7D;;;OAGG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOpD;AAqCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,GAAE,gBAAqB,GAAG,CAAC,CAUjF"}

package/lib/app/utils/defineEnv.js

@@ -0,0 +1,95 @@
+/**
+ * `defineEnv` — boot-time environment validation.
+ *
+ * Accepts any schema with a `safeParse(data) -> { success, data | error }` shape
+ * (Zod 3, Zod 4, Valibot adapter, etc.) so the framework stays validator-agnostic
+ * at the type level. On failure: prints a structured "missing/invalid: VAR (type)"
+ * report and exits with code 1 *before* the app boots.
+ *
+ * Replaces the v3 pattern of scattered `process.env.FOO || ""` reads with a single
+ * typed env object. Eliminates the class of "mystery runtime errors from a typo'd
+ * env var" by failing loudly at startup.
+ */
+/**
+ * Replace common secret-value shapes with `<redacted>` before logging.
+ *
+ * Framework-default Zod messages don't include the raw value (e.g.
+ * "String must contain at least 32 character(s)"), but consumer
+ * schemas using `.refine((v) => …, { message: `got "${v}"` })` or
+ * transform-based validators that include the raw value will spill
+ * the secret through this `console.error` path — observability
+ * stacks (Stackdriver, Datadog, Loki) capture stdout/stderr by
+ * default, and the secret then becomes searchable, indexed, and
+ * forwarded across systems. A regex scrub here is the last line of
+ * defense before that boundary.
+ *
+ * The patterns are intentionally narrow (named token shapes) plus
+ * one generic-high-entropy catch-all. False positives are limited
+ * to error messages that happen to contain ≥32 contiguous
+ * base64-alphabet characters with no separators — rare in legit
+ * Zod messages.
+ */
+export function scrubSecrets(message) {
+    if (typeof message !== "string" || message.length === 0)
+        return message;
+    let out = message;
+    for (const pattern of SECRET_PATTERNS) {
+        out = out.replace(pattern, "<redacted>");
+    }
+    return out;
+}
+// Ordered most-specific → least-specific so named shapes don't get
+// pre-swallowed by the generic high-entropy catch.
+const SECRET_PATTERNS = [
+    // JWT-shaped (three base64url segments separated by `.`)
+    /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
+    // OpenAI / Anthropic-style `sk-…` keys
+    /\bsk-[A-Za-z0-9_-]{20,}\b/g,
+    // Slack tokens (`xoxb-…`, `xoxp-…`, `xoxa-…`)
+    /\bxox[abp]-[A-Za-z0-9-]{10,}\b/g,
+    // AWS access key IDs
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    // Generic high-entropy: contiguous run of 32+ base64-ish characters
+    // with no spaces. Last resort for "we don't know the prefix but
+    // the value is obviously a token."
+    /[A-Za-z0-9+/=_-]{32,}/g,
+];
+function defaultOnFailure(issues, logger) {
+    logger.error("");
+    logger.error("✗ Environment validation failed. The app cannot start.");
+    logger.error("");
+    for (const issue of issues) {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
+        const safeMessage = scrubSecrets(issue.message);
+        logger.error(`  • ${path}: ${safeMessage}${issue.code ? ` [${issue.code}]` : ""}`);
+    }
+    logger.error("");
+    logger.error(`Total: ${issues.length} issue(s). Fix the env vars listed above and restart.`);
+    logger.error("");
+    process.exit(1);
+}
+/**
+ * Validate process.env against a schema. Returns the typed env on success;
+ * exits the process with a structured error report on failure.
+ *
+ * @example
+ *   import { z } from "zod";
+ *   const schema = z.object({
+ *     PORT: z.coerce.number().int().positive().default(3000),
+ *     DATABASE_URL: z.string().url(),
+ *     SESSION_SECRET: z.string().min(32),
+ *   });
+ *   export const env = defineEnv(schema);
+ *   // env.PORT is typed as number, env.DATABASE_URL as string, etc.
+ */
+export function defineEnv(schema, opts = {}) {
+    const source = opts.source ?? process.env;
+    const logger = opts.logger ?? console;
+    const onFailure = opts.onFailure ?? ((issues) => defaultOnFailure(issues, logger));
+    const result = schema.safeParse(source);
+    if (result.success) {
+        return result.data;
+    }
+    return onFailure(result.error.issues);
+}
+//# sourceMappingURL=defineEnv.js.map

package/lib/app/utils/defineEnv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineEnv.js","sourceRoot":"","sources":["../../../src/app/utils/defineEnv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwCH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACxE,IAAI,GAAG,GAAG,OAAO,CAAC;IAClB,KAAK,MAAM,OAAO,IAAI,eAAe,EAAE,CAAC;QACtC,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,mEAAmE;AACnE,mDAAmD;AACnD,MAAM,eAAe,GAAsB;IACzC,yDAAyD;IACzD,gEAAgE;IAChE,uCAAuC;IACvC,4BAA4B;IAC5B,8CAA8C;IAC9C,iCAAiC;IACjC,qBAAqB;IACrB,uBAAuB;IACvB,oEAAoE;IACpE,gEAAgE;IAChE,mCAAmC;IACnC,wBAAwB;CACzB,CAAC;AAEF,SAAS,gBAAgB,CACvB,MAAqC,EACrC,MAA8B;IAE9B,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACjB,MAAM,CAAC,KAAK,CAAC,wDAAwD,CAAC,CAAC;IACvE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACjB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACrE,MAAM,WAAW,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAChD,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACrF,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACjB,MAAM,CAAC,KAAK,CAAC,UAAU,MAAM,CAAC,MAAM,uDAAuD,CAAC,CAAC;IAC7F,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACjB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAI,MAAoB,EAAE,OAAyB,EAAE;IAC5E,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC;IACtC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAEnF,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IACD,OAAO,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC"}