@xcelsior/storage-api 1.0.0

package/cdk.context.json

@@ -0,0 +1,6 @@
+{
+  "hosted-zone:account=192933325589:domainName=xcelsior.co:region=ap-southeast-2": {
+    "Id": "/hostedzone/Z08595403217R035ZUO3M",
+    "Name": "xcelsior.co."
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@xcelsior/storage-api",
+  "version": "1.0.0",
+  "type": "module",
+  "files": [
+    "packages/**",
+    "stacks/**",
+    "*.json",
+    "sst.config.ts"
+  ],
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.888.0",
+    "@aws-sdk/s3-request-presigner": "^3.888.0",
+    "sst": "^2.40.3",
+    "zod": "^3.22.4",
+    "@types/aws-lambda": "^8.10.152",
+    "aws-cdk-lib": "2.201.0",
+    "constructs": "10.3.0",
+    "dotenv": "^17.2.1",
+    "typescript": "^5.3.3",
+    "@tsconfig/node18": "^18.2.2",
+    "@types/node": "^20.11.16",
+    "@xcelsior/aws": "1.0.6",
+    "@xcelsior/monitoring": "1.0.4",
+    "@xcelsior/lambda-http": "1.0.5"
+  },
+  "scripts": {
+    "dev": "sst dev --stage dev --mode basic",
+    "build": "sst build",
+    "deploy": "sst deploy",
+    "remove": "sst remove",
+    "console": "sst console",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/packages/functions/config.ts

@@ -0,0 +1,35 @@
+import { createLogger, createTracer } from '@xcelsior/lambda-http';
+
+// ─── Bucket names ─────────────────────────────────────────────────────────────
+// Injected as CloudFormation-resolved env vars by StorageStack
+export const PUBLIC_BUCKET_NAME = process.env.PUBLIC_BUCKET_NAME!;
+export const SECURE_BUCKET_NAME = process.env.SECURE_BUCKET_NAME!;
+
+// ─── CloudFront domains ───────────────────────────────────────────────────────
+export const PUBLIC_CLOUDFRONT_DOMAIN = process.env.PUBLIC_CLOUDFRONT_DOMAIN!;
+export const SECURE_CLOUDFRONT_DOMAIN = process.env.SECURE_CLOUDFRONT_DOMAIN!;
+
+// ─── Upload config ────────────────────────────────────────────────────────────
+/** Maximum file size the API will accept (MB). Validated in the request schema. */
+export const MAX_FILE_SIZE_BYTES = Number(process.env.MAX_FILE_SIZE_MB || '100') * 1024 * 1024;
+
+/** How long presigned upload URLs and HMAC-signed access URLs are valid (seconds). Default: 5 min. */
+export const PRESIGNED_URL_EXPIRY_SECONDS = Number(
+    process.env.PRESIGNED_URL_EXPIRY_SECONDS || '300'
+);
+
+/**
+ * HMAC-SHA256 signing key shared between this Lambda and the CloudFront Function.
+ * Used to produce per-file tokens — never placed directly in any URL.
+ */
+export const SECURE_STORAGE_ACCESS_SECRET = process.env.SECURE_STORAGE_ACCESS_SECRET!;
+
+// ─── Observability ────────────────────────────────────────────────────────────
+export const logger = createLogger('@xcelsior/storage');
+const tracer = createTracer('@xcelsior/storage');
+
+export const middlewareConfig = {
+    logger,
+    tracer,
+    cors: { origin: '*' },
+};

package/packages/functions/sst-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="sst/node/api" />

package/packages/functions/storage/getPublicUploadUrl.ts

@@ -0,0 +1,88 @@
+import { randomUUID } from 'node:crypto';
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { z } from 'zod';
+import { S3Service } from '@xcelsior/aws/src/s3';
+import { middyfy, ValidationError } from '@xcelsior/lambda-http';
+import {
+    PUBLIC_BUCKET_NAME,
+    PUBLIC_CLOUDFRONT_DOMAIN,
+    MAX_FILE_SIZE_BYTES,
+    PRESIGNED_URL_EXPIRY_SECONDS,
+    logger,
+    middlewareConfig,
+} from '../config';
+
+const schema = z.object({
+    /** Original file name — used to preserve the extension */
+    fileName: z.string().min(1).max(255),
+    /** MIME type (e.g. "image/png", "application/pdf") */
+    contentType: z.string().min(1),
+    /** File size in bytes — validated against MAX_FILE_SIZE_MB */
+    fileSize: z
+        .number()
+        .int()
+        .positive()
+        .max(MAX_FILE_SIZE_BYTES, {
+            message: `File size must not exceed ${MAX_FILE_SIZE_BYTES / 1024 / 1024} MB`,
+        }),
+    /**
+     * Optional sub-folder (e.g. "avatars", "documents").
+     * Sanitised to prevent path traversal.
+     */
+    folder: z
+        .string()
+        .regex(
+            /^[a-zA-Z0-9_\-/]+$/,
+            'folder must contain only alphanumeric, dash, underscore or slash characters'
+        )
+        .optional(),
+});
+
+const getPublicUploadUrlHandler = async (event: APIGatewayProxyEventV2) => {
+    let body: z.infer<typeof schema>;
+    try {
+        body = schema.parse(event.body);
+    } catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new ValidationError('Invalid request body', error.errors);
+        }
+        throw error;
+    }
+
+    const { fileName, contentType, fileSize, folder } = body;
+
+    // Build a collision-free object key
+    const ext =
+        fileName
+            .split('.')
+            .pop()
+            ?.toLowerCase()
+            .replace(/[^a-z0-9]/g, '') || 'bin';
+    const prefix = folder ? `${folder}/` : 'uploads/';
+    const key = `${prefix}${randomUUID()}.${ext}`;
+
+    logger.info('Generating presigned public upload URL', { fileName, contentType, fileSize, key });
+
+    const uploadUrl = await S3Service.generatePresignedUploadUrl(
+        PUBLIC_BUCKET_NAME,
+        key,
+        contentType,
+        PRESIGNED_URL_EXPIRY_SECONDS
+    );
+
+    // Permanent CloudFront URL — no auth required, never expires
+    const fileUrl = `https://${PUBLIC_CLOUDFRONT_DOMAIN}/${key}`;
+
+    logger.info('Presigned public upload URL generated', { key, fileUrl });
+
+    return {
+        /** PUT to this URL to upload the file. Expires in `expiresIn` seconds. */
+        uploadUrl,
+        /** Permanent CloudFront URL — use this to read/serve the file after upload. */
+        fileUrl,
+        key,
+        expiresIn: PRESIGNED_URL_EXPIRY_SECONDS,
+    };
+};
+
+export const handler = middyfy(getPublicUploadUrlHandler, middlewareConfig);

package/packages/functions/storage/getSecureUploadUrl.ts

@@ -0,0 +1,110 @@
+import { randomUUID } from 'node:crypto';
+import { createHmac } from 'node:crypto';
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { z } from 'zod';
+import { S3Service } from '@xcelsior/aws/src/s3';
+import { middyfy, ValidationError } from '@xcelsior/lambda-http';
+import {
+    SECURE_BUCKET_NAME,
+    SECURE_CLOUDFRONT_DOMAIN,
+    SECURE_STORAGE_ACCESS_SECRET,
+    MAX_FILE_SIZE_BYTES,
+    PRESIGNED_URL_EXPIRY_SECONDS,
+    logger,
+    middlewareConfig,
+} from '../config';
+
+const schema = z.object({
+    /** Original file name — used to preserve the extension */
+    fileName: z.string().min(1).max(255),
+    /** MIME type (e.g. "application/pdf", "image/jpeg") */
+    contentType: z.string().min(1),
+    /** File size in bytes — validated against MAX_FILE_SIZE_MB */
+    fileSize: z
+        .number()
+        .int()
+        .positive()
+        .max(MAX_FILE_SIZE_BYTES, {
+            message: `File size must not exceed ${MAX_FILE_SIZE_BYTES / 1024 / 1024} MB`,
+        }),
+    /**
+     * Optional sub-folder (e.g. "contracts", "invoices").
+     * Sanitised to prevent path traversal.
+     */
+    folder: z
+        .string()
+        .regex(
+            /^[a-zA-Z0-9_\-/]+$/,
+            'folder must contain only alphanumeric, dash, underscore or slash characters'
+        )
+        .optional(),
+});
+
+/**
+ * Generates a permanent per-file HMAC-SHA256 token for CloudFront access.
+ *
+ * The signed message is the CloudFront request URI (e.g. `/secure-uploads/uuid.pdf`).
+ * The token is unique per file because the UUID key is part of the URI.
+ * A token for one file cannot be used to access a different file.
+ * The URL never expires — revocation requires rotating SECURE_STORAGE_ACCESS_SECRET.
+ */
+function generateFileToken(uri: string): string {
+    return createHmac('sha256', SECURE_STORAGE_ACCESS_SECRET).update(uri).digest('hex');
+}
+
+const getSecureUploadUrlHandler = async (event: APIGatewayProxyEventV2) => {
+    let body: z.infer<typeof schema>;
+    try {
+        body = schema.parse(event.body);
+    } catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new ValidationError('Invalid request body', error.errors);
+        }
+        throw error;
+    }
+
+    const { fileName, contentType, fileSize, folder } = body;
+
+    // Build a collision-free object key
+    const ext =
+        fileName
+            .split('.')
+            .pop()
+            ?.toLowerCase()
+            .replace(/[^a-z0-9]/g, '') || 'bin';
+    const prefix = folder ? `${folder}/` : 'secure-uploads/';
+    const key = `${prefix}${randomUUID()}.${ext}`;
+
+    // CloudFront uses a leading-slash URI (e.g. /secure-uploads/uuid.pdf)
+    const uri = `/${key}`;
+    const token = generateFileToken(uri);
+
+    logger.info('Generating presigned secure upload URL', { fileName, contentType, fileSize, key });
+
+    const uploadUrl = await S3Service.generatePresignedUploadUrl(
+        SECURE_BUCKET_NAME,
+        key,
+        contentType,
+        PRESIGNED_URL_EXPIRY_SECONDS
+    );
+
+    /**
+     * Permanent per-file CloudFront URL.
+     * ?token=<hex> — HMAC-SHA256(signingSecret, uri) — unique per file, never expires.
+     * The shared signing secret is never in this URL.
+     */
+    const fileUrl = `https://${SECURE_CLOUDFRONT_DOMAIN}${uri}?token=${token}`;
+
+    logger.info('Presigned secure upload URL generated', { key });
+
+    return {
+        /** PUT to this URL to upload the file. Expires in `uploadExpiresIn` seconds. */
+        uploadUrl,
+        /** Permanent HMAC-signed CloudFront URL — unique per file, never expires. */
+        fileUrl,
+        key,
+        uploadExpiresIn: PRESIGNED_URL_EXPIRY_SECONDS,
+    };
+};
+
+export const handler = middyfy(getSecureUploadUrlHandler, middlewareConfig);

package/sst.config.ts

@@ -0,0 +1,15 @@
+import 'dotenv/config';
+import type { SSTConfig } from 'sst';
+import { StorageStack } from './stacks/StorageStack';
+
+export default {
+    config(_input) {
+        return {
+            name: 'storage',
+            region: 'ap-southeast-2',
+        };
+    },
+    stacks(app) {
+        app.stack(StorageStack);
+    },
+} satisfies SSTConfig;

package/stacks/StorageStack.ts

@@ -0,0 +1,429 @@
+import 'dotenv/config';
+import { ApiGatewayV1Api, type StackContext } from 'sst/constructs';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as cloudfront from 'aws-cdk-lib/aws-cloudfront';
+import * as origins from 'aws-cdk-lib/aws-cloudfront-origins';
+import * as acm from 'aws-cdk-lib/aws-certificatemanager';
+import { CertificateValidation } from 'aws-cdk-lib/aws-certificatemanager';
+import * as route53 from 'aws-cdk-lib/aws-route53';
+import { Duration, RemovalPolicy } from 'aws-cdk-lib';
+
+// ─── Config helpers ──────────────────────────────────────────────────────────
+
+function requireEnv(name: string): string {
+    const value = process.env[name];
+    if (!value) throw new Error(`Environment variable "${name}" is required`);
+    return value;
+}
+
+/**
+ * Builds a CloudFront Function (runtime 2.0, async) that validates a
+ * permanent per-file HMAC-SHA256 token delivered via `?token=<hex>`.
+ *
+ * How it works
+ * ─────────────
+ * 1. The Lambda generates a token: HMAC-SHA256(signingSecret, uri)
+ * 2. CloudFront Function re-computes the same HMAC and compares it with the
+ *    token in the query string.
+ * 3. If the HMAC matches, the request is forwarded to S3 (token stripped so
+ *    it never appears in S3 access logs).
+ *
+ * Security properties
+ * ────────────────────
+ * • The signing secret is never in any URL — only its HMAC derivative is.
+ * • Each file gets a different token because the UUID URI is the signed message.
+ * • A token for /a/b.pdf cannot be used for /a/c.pdf.
+ * • URLs never expire; rotate SECURE_STORAGE_ACCESS_SECRET to revoke all tokens.
+ *
+ * NOTE: The signing secret is embedded in the function source and is therefore
+ * visible in the CloudFront console. For higher-sensitivity workloads, migrate
+ * to CloudFront Functions runtime 2.0 + KeyValueStore.
+ */
+function buildSecureAccessFunctionCode(signingSecret: string): string {
+    const escaped = signingSecret.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    return `
+function hexToBytes(hex) {
+    var len = hex.length / 2;
+    var out = new Uint8Array(len);
+    for (var i = 0; i < len; i++) {
+        out[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+
+function deny(msg) {
+    return {
+        statusCode: 403,
+        statusDescription: 'Forbidden',
+        headers: { 'content-type': { value: 'application/json' } },
+        body: '{"error":"' + msg + '"}'
+    };
+}
+
+async function handler(event) {
+    var request = event.request;
+    var tokenP  = request.querystring['token'];
+
+    if (!tokenP) {
+        return deny('Missing token.');
+    }
+
+    try {
+        var key = await crypto.subtle.importKey(
+            'raw',
+            new TextEncoder().encode('${escaped}'),
+            { name: 'HMAC', hash: 'SHA-256' },
+            false,
+            ['verify']
+        );
+        var ok = await crypto.subtle.verify(
+            'HMAC',
+            key,
+            hexToBytes(tokenP.value),
+            new TextEncoder().encode(request.uri)
+        );
+        if (!ok) return deny('Invalid token.');
+    } catch (_) {
+        return deny('Token validation failed.');
+    }
+
+    delete request.querystring['token'];
+    return request;
+}`.trim();
+}
+
+// ─── Stack ───────────────────────────────────────────────────────────────────
+
+export function StorageStack({ stack }: StackContext) {
+    const domainName = process.env.API_DOMAIN_NAME || 'xcelsior.co';
+    const isProd = ['production', 'prod'].includes(stack.stage);
+
+    // ── Configurable feature flags ──────────────────────────────────────────
+    // Versioning is configured independently for each bucket
+    const enableVersioningPublic = process.env.ENABLE_VERSIONING_PUBLIC === 'true';
+    const enableVersioningSecure = process.env.ENABLE_VERSIONING_SECURE === 'true';
+    const maxFileSizeMb = Number(process.env.MAX_FILE_SIZE_MB || '100');
+    const presignedUrlExpiry = Number(process.env.PRESIGNED_URL_EXPIRY_SECONDS || '300');
+
+    // ── Secure-bucket access secret ─────────────────────────────────────────
+    const accessSecret = requireEnv('SECURE_STORAGE_ACCESS_SECRET');
+
+    // ── Optional custom-domain config ───────────────────────────────────────
+    // Certificates are created automatically via DNS validation — no ARN needed.
+    const publicStorageDomain = process.env.PUBLIC_STORAGE_DOMAIN || '';
+    const secureStorageDomain = process.env.SECURE_STORAGE_DOMAIN || '';
+    const hostedZoneId = process.env.HOSTED_ZONE_ID || '';
+
+    // ── API subdomain ────────────────────────────────────────────────────────
+    const apiSubdomain = isProd
+        ? `storage.api.${domainName}`
+        : `${stack.stage}-storage.api.${domainName}`;
+
+    // ────────────────────────────────────────────────────────────────────────
+    // 1. S3 Buckets
+    // Both buckets are fully private; CloudFront is the only public entry point.
+    // ────────────────────────────────────────────────────────────────────────
+
+    const sharedCorsRules: s3.CorsRule[] = [
+        {
+            allowedOrigins: ['*'],
+            allowedHeaders: ['*'],
+            allowedMethods: [
+                s3.HttpMethods.GET,
+                s3.HttpMethods.PUT,
+                s3.HttpMethods.POST,
+                s3.HttpMethods.HEAD,
+            ],
+            maxAge: 86400, // 1 day
+            exposedHeaders: ['ETag'],
+        },
+    ];
+
+    function lifecycleRules(versioned: boolean): s3.LifecycleRule[] {
+        return versioned
+            ? [
+                  {
+                      enabled: true,
+                      // Retain the 5 most recent non-current versions
+                      noncurrentVersionsToRetain: 5,
+                      // Hard-delete older non-current versions after 90 days
+                      noncurrentVersionExpiration: Duration.days(90),
+                      // Clean up stalled multipart uploads after 7 days
+                      abortIncompleteMultipartUploadAfter: Duration.days(7),
+                  },
+              ]
+            : [
+                  {
+                      enabled: true,
+                      abortIncompleteMultipartUploadAfter: Duration.days(7),
+                  },
+              ];
+    }
+
+    /** Public bucket — files are served to anyone via CloudFront */
+    const publicBucket = new s3.Bucket(stack, 'StoragePublicBucket', {
+        versioned: enableVersioningPublic,
+        blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+        enforceSSL: true,
+        removalPolicy: isProd ? RemovalPolicy.RETAIN : RemovalPolicy.DESTROY,
+        ...(isProd ? {} : { autoDeleteObjects: true }),
+        cors: sharedCorsRules,
+        lifecycleRules: lifecycleRules(enableVersioningPublic),
+    });
+
+    /**
+     * Secure bucket — files are private; access is via permanent HMAC-signed
+     * CloudFront URLs (?token=<hex>) issued by the upload Lambda. Each file
+     * receives a unique token; the signing secret is never placed in any URL.
+     */
+    const secureBucket = new s3.Bucket(stack, 'StorageSecureBucket', {
+        versioned: enableVersioningSecure,
+        blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+        enforceSSL: true,
+        // Encrypt at rest with SSE-S3 (default since Jan 2023, explicit here for clarity)
+        encryption: s3.BucketEncryption.S3_MANAGED,
+        removalPolicy: isProd ? RemovalPolicy.RETAIN : RemovalPolicy.DESTROY,
+        ...(isProd ? {} : { autoDeleteObjects: true }),
+        cors: sharedCorsRules,
+        lifecycleRules: lifecycleRules(enableVersioningSecure),
+    });
+
+    // ────────────────────────────────────────────────────────────────────────
+    // 2. CloudFront Function — validates the access secret on the secure dist
+    // ────────────────────────────────────────────────────────────────────────
+
+    const secureAccessFunction = new cloudfront.Function(stack, 'SecureAccessFunction', {
+        functionName: `${stack.stage}-storage-secure-access`,
+        // Runtime 2.0 is required for async handlers and the Web Crypto API (crypto.subtle)
+        runtime: cloudfront.FunctionRuntime.JS_2_0,
+        code: cloudfront.FunctionCode.fromInline(buildSecureAccessFunctionCode(accessSecret)),
+        comment: `HMAC-SHA256 per-file token validation for secure storage [${stack.stage}]`,
+    });
+
+    // ────────────────────────────────────────────────────────────────────────
+    // 3. CloudFront Origins (OAC — recommended over legacy OAI)
+    //    S3BucketOrigin.withOriginAccessControl() automatically:
+    //      • Creates an S3 Origin Access Control
+    //      • Adds a bucket-policy statement granting cloudfront.amazonaws.com
+    //        s3:GetObject scoped to the specific distribution ARN
+    // ────────────────────────────────────────────────────────────────────────
+
+    const publicOrigin = origins.S3BucketOrigin.withOriginAccessControl(publicBucket);
+    const secureOrigin = origins.S3BucketOrigin.withOriginAccessControl(secureBucket);
+
+    // ────────────────────────────────────────────────────────────────────────
+    // 4. CloudFront Distributions
+    // ────────────────────────────────────────────────────────────────────────
+
+    // ────────────────────────────────────────────────────────────────────────
+    // 4+5. CloudFront Distributions + optional custom domains
+    //
+    // When PUBLIC_STORAGE_DOMAIN / SECURE_STORAGE_DOMAIN are set (and
+    // HOSTED_ZONE_ID is provided), we automatically:
+    //   a) Create an ACM certificate in us-east-1 via DNS validation
+    //      (DnsValidatedCertificate deploys a custom-resource Lambda that
+    //       creates & validates the cert in the correct region for CloudFront)
+    //   b) Attach it to the distribution
+    //   c) Create a Route53 alias A-record pointing to the distribution
+    // ────────────────────────────────────────────────────────────────────────
+
+    const hostedZone = route53.HostedZone.fromLookup(stack, 'hosted-zone', {
+        domainName: domainName,
+    });
+
+    function buildDistributionDomain(
+        certId: string,
+        domain: string
+    ): { domainNames: string[]; certificate: acm.ICertificate } | Record<string, never> {
+        if (!domain || !hostedZone) return {};
+        // DnsValidatedCertificate creates the cert in us-east-1 (required by CloudFront)
+        // and adds the DNS validation CNAME to the hosted zone automatically.
+        const certificate = new acm.DnsValidatedCertificate(stack, certId, {
+            domainName: domain,
+            hostedZone: hostedZone,
+            region: 'us-east-1',
+        });
+        return { domainNames: [domain], certificate: certificate };
+    }
+
+    /** Public distribution — standard CDN, response is cached and compressed */
+    const publicDistribution = new cloudfront.Distribution(stack, 'PublicStorageDistribution', {
+        comment: `Public storage CDN [${stack.stage}]`,
+        defaultBehavior: {
+            origin: publicOrigin,
+            viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
+            cachePolicy: cloudfront.CachePolicy.CACHING_OPTIMIZED,
+            allowedMethods: cloudfront.AllowedMethods.ALLOW_GET_HEAD_OPTIONS,
+            cachedMethods: cloudfront.CachedMethods.CACHE_GET_HEAD_OPTIONS,
+            compress: true,
+        },
+        ...buildDistributionDomain('PublicStorageCert', publicStorageDomain),
+    });
+
+    /**
+     * Secure distribution — caching disabled so every request passes through
+     * the CloudFront Function that validates the per-file HMAC token.
+     */
+    const secureDistribution = new cloudfront.Distribution(stack, 'SecureStorageDistribution', {
+        comment: `Secure storage CDN [${stack.stage}]`,
+        defaultBehavior: {
+            origin: secureOrigin,
+            viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
+            cachePolicy: cloudfront.CachePolicy.CACHING_DISABLED,
+            allowedMethods: cloudfront.AllowedMethods.ALLOW_GET_HEAD_OPTIONS,
+            cachedMethods: cloudfront.CachedMethods.CACHE_GET_HEAD_OPTIONS,
+            compress: true,
+            functionAssociations: [
+                {
+                    function: secureAccessFunction,
+                    eventType: cloudfront.FunctionEventType.VIEWER_REQUEST,
+                },
+            ],
+        },
+        ...buildDistributionDomain('SecureStorageCert', secureStorageDomain),
+    });
+
+    // ────────────────────────────────────────────────────────────────────────
+    // 6. Lambda API
+    // ────────────────────────────────────────────────────────────────────────
+
+    const publicCdnDomain = publicStorageDomain || publicDistribution.distributionDomainName;
+    const secureCdnDomain = secureStorageDomain || secureDistribution.distributionDomainName;
+
+    const commonEnv: Record<string, string> = {
+        MONITORING_PROVIDER: process.env.MONITORING_PROVIDER ?? '',
+        SENTRY_DSN: process.env.SENTRY_DSN ?? '',
+        ROLLBAR_ACCESS_TOKEN: process.env.ROLLBAR_ACCESS_TOKEN ?? '',
+        POWERTOOLS_SERVICE_NAME: '@xcelsior/storage',
+        POWERTOOLS_METRICS_NAMESPACE: 'ExcelsiorStorage',
+        POWERTOOLS_LOGGER_LOG_LEVEL: 'INFO',
+        POWERTOOLS_LOGGER_LOG_EVENT: 'true',
+        POWERTOOLS_DEV: stack.stage === 'dev' ? 'true' : '',
+        LOGTAIL_TOKEN: process.env.LOGTAIL_TOKEN ?? '',
+        LOGTAIL_HTTP_API_URL: process.env.LOGTAIL_HTTP_API_URL ?? '',
+        APP_ENV: stack.stage,
+        NODE_ENV: stack.stage === 'dev' ? 'development' : 'production',
+        AWS_NODEJS_CONNECTION_REUSE_ENABLED: '1',
+        // Runtime config
+        MAX_FILE_SIZE_MB: String(maxFileSizeMb),
+        PRESIGNED_URL_EXPIRY_SECONDS: String(presignedUrlExpiry),
+        PUBLIC_VERSIONING_ENABLED: String(enableVersioningPublic),
+        SECURE_VERSIONING_ENABLED: String(enableVersioningSecure),
+        // HMAC signing key — used by the secure-upload Lambda to produce per-file tokens
+        // that the CloudFront Function validates. Never appears in any generated URL.
+        SECURE_STORAGE_ACCESS_SECRET: accessSecret,
+        // CDN domains (resolved by CloudFormation at deploy time)
+        PUBLIC_CLOUDFRONT_DOMAIN: publicCdnDomain,
+        SECURE_CLOUDFRONT_DOMAIN: secureCdnDomain,
+    };
+
+    const api = new ApiGatewayV1Api(stack, 'StorageApi', {
+        customDomain: {
+            domainName: apiSubdomain,
+            hostedZone: domainName,
+        },
+        defaults: {
+            function: {
+                layers: [
+                    'arn:aws:lambda:ap-southeast-2:192933325589:layer:logtail-lambda-extension:1',
+                ],
+                environment: commonEnv,
+                nodejs: { esbuild: { minify: true } },
+                runtime: 'nodejs22.x',
+                tracing: 'active',
+            },
+        },
+        cors: true,
+        routes: {
+            /**
+             * POST /api/storage/public/upload-url
+             * Returns a presigned S3 PutObject URL for the public bucket.
+             * The uploaded file will be publicly accessible via CloudFront.
+             */
+            'POST /api/storage/public/upload-url': {
+                function: {
+                    handler: 'packages/functions/storage/getPublicUploadUrl.handler',
+                    functionName: `${stack.stage}-storage-get-public-upload-url-function`,
+                    environment: {
+                        // Resolved by CloudFormation; not available as SST binding
+                        // because we use a native CDK bucket for full versioning control
+                        PUBLIC_BUCKET_NAME: publicBucket.bucketName,
+                    },
+                },
+                cdk: { method: { apiKeyRequired: true } },
+            },
+
+            /**
+             * POST /api/storage/secure/upload-url
+             * Returns a presigned S3 PutObject URL (for uploading) and a CloudFront URL
+             * with a permanent per-file HMAC-SHA256 token (?token=…) for reading.
+             * Each file receives a unique, time-limited token — the shared signing secret
+             * is never present in any URL.
+             */
+            'POST /api/storage/secure/upload-url': {
+                function: {
+                    handler: 'packages/functions/storage/getSecureUploadUrl.handler',
+                    functionName: `${stack.stage}-storage-get-secure-upload-url-function`,
+                    environment: {
+                        SECURE_BUCKET_NAME: secureBucket.bucketName,
+                    },
+                },
+                cdk: { method: { apiKeyRequired: true } },
+            },
+        },
+    });
+
+    const publicUploadFn = api.getFunction('POST /api/storage/public/upload-url');
+    const secureUploadFn = api.getFunction('POST /api/storage/secure/upload-url');
+
+    // Public upload: only needs s3:PutObject to sign the upload URL
+    if (publicUploadFn) publicBucket.grantPut(publicUploadFn);
+
+    // Secure upload: only needs s3:PutObject — the access URL is an HMAC-signed
+    // CloudFront URL, so no s3:GetObject is required on the Lambda side
+    if (secureUploadFn) secureBucket.grantPut(secureUploadFn);
+
+    // ────────────────────────────────────────────────────────────────────────
+    // 7. API key + usage plan (all routes require the key)
+    // ────────────────────────────────────────────────────────────────────────
+
+    const apiKey = api.cdk.restApi.addApiKey('StorageApiKey', {
+        apiKeyName: `storage-api-key-${stack.stage}`,
+    });
+
+    const usagePlan = api.cdk.restApi.addUsagePlan('StorageApiUsagePlan', {
+        name: `storage-usage-plan-${stack.stage}`,
+        apiStages: [
+            {
+                api: api.cdk.restApi,
+                stage: api.cdk.restApi.deploymentStage,
+            },
+        ],
+    });
+
+    usagePlan.addApiKey(apiKey);
+
+    // ────────────────────────────────────────────────────────────────────────
+    // 8. Outputs
+    // ────────────────────────────────────────────────────────────────────────
+
+    stack.addOutputs({
+        ApiEndpoint: api.url,
+        PublicBucketName: publicBucket.bucketName,
+        SecureBucketName: secureBucket.bucketName,
+        PublicCloudFrontDomain: publicDistribution.distributionDomainName,
+        SecureCloudFrontDomain: secureDistribution.distributionDomainName,
+        ...(publicStorageDomain ? { PublicCustomDomain: `https://${publicStorageDomain}` } : {}),
+        ...(secureStorageDomain ? { SecureCustomDomain: `https://${secureStorageDomain}` } : {}),
+        PublicVersioningEnabled: String(enableVersioningPublic),
+        SecureVersioningEnabled: String(enableVersioningSecure),
+    });
+
+    return {
+        api,
+        publicBucket,
+        secureBucket,
+        publicDistribution,
+        secureDistribution,
+    };
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+    "extends": "@tsconfig/node18/tsconfig.json",
+    "compilerOptions": {
+        "module": "esnext",
+        "outDir": "dist",
+        "moduleResolution": "node",
+        "baseUrl": ".",
+        "skipLibCheck": true,
+        "paths": {
+            "@xcelsior/storage-api/*": ["*"]
+        }
+    },
+    "include": ["packages/**/*.ts", "stacks/**/*.ts", "sst.config.ts"]
+}