@revealui/core 0.12.2 → 0.13.0

package/dist/revforge-license-boot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revforge-license-boot.d.ts","sourceRoot":"","sources":["../src/revforge-license-boot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,8BAA8B,wCAAwC,CAAC;AAEpF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAa5D;AAED;;;;;;;;;GASG;AACH,wBAAsB,6BAA6B,CACjD,GAAG,GAAE,MAA8B,GAClC,OAAO,CAAC,IAAI,CAAC,CA6Ef"}

package/dist/revforge-license-boot.js

@@ -0,0 +1,115 @@
+/**
+ * Shared Forge / self-host license boot gate for apps/admin + apps/server.
+ *
+ * Extracted from the intentional admin/server dual after the 2026-08-02 fleet
+ * redundancy audit. Server previously owned the full check (customer id, kid
+ * mismatch, domain binding); admin had a shortened copy. One implementation
+ * so the two cannot drift (instrumentation.ts TODO resolved).
+ *
+ * Throws on failure. Callers that must not throw (Next.js instrumentation)
+ * catch and `process.exit(1)`.
+ */
+import { detectDeploymentMode as detectDeploymentModeCore, } from './deployment-mode.js';
+import { computeKeyId, hostMatchesLicensedDomains, validateLicenseKey } from './license.js';
+import { logger } from './observability/logger.js';
+/**
+ * GAP-436 (owner-ruled 2026-07-26): plain OSS/self-host opt-in when no key is
+ * present. Stamped RevForge kits always bake a key, so they never hit this.
+ */
+export const ALLOW_UNLICENSED_SELF_HOST_ENV = 'REVEALUI_ALLOW_UNLICENSED_SELF_HOST';
+/**
+ * Extracts the `kid` (key id) from a JWT protected header WITHOUT verifying
+ * the signature. Used only to sharpen error messages after cryptographic
+ * verification has already failed.
+ */
+export function decodeJwtKid(jwt) {
+    const headerSegment = jwt.split('.')[0];
+    if (!headerSegment)
+        return undefined;
+    try {
+        const header = JSON.parse(Buffer.from(headerSegment, 'base64url').toString('utf8'));
+        if (header && typeof header === 'object' && 'kid' in header) {
+            const { kid } = header;
+            return typeof kid === 'string' ? kid : undefined;
+        }
+    }
+    catch {
+        // Malformed header — caller surfaces generic invalid-license error.
+    }
+    return undefined;
+}
+/**
+ * Forge-mode license enforcement at process boot.
+ *
+ * - Hosted mode: no-op.
+ * - Forge mode + no key + ALLOW_UNLICENSED_SELF_HOST: Free (OSS) tier log, return.
+ * - Forge mode otherwise: require key + public key, verify JWT, optional
+ *   customerId + domain binding.
+ *
+ * Honors `SKIP_ENV_VALIDATION=true` for Docker build / tests.
+ */
+export async function validateForgeLicenseAtStartup(env = process.env) {
+    if (env.SKIP_ENV_VALIDATION === 'true') {
+        return;
+    }
+    const mode = detectDeploymentModeCore(env);
+    if (mode !== 'forge') {
+        return;
+    }
+    if (!env.REVEALUI_LICENSE_KEY) {
+        if (env[ALLOW_UNLICENSED_SELF_HOST_ENV] === 'true') {
+            logger.info('no license key — running Free (OSS) tier');
+            return;
+        }
+        throw new Error('LICENSE VALIDATION FAILED: REVEALUI_LICENSE_KEY is required for RevForge deployments. ' +
+            'Run bin/revvault-bootstrap.sh to materialize docker/.env from revvault, ' +
+            'or contact the operator who stamped this kit. A plain self-host deployment that ' +
+            `intends to run without a license should set ${ALLOW_UNLICENSED_SELF_HOST_ENV}=true to ` +
+            'boot at Free (OSS) tier instead.');
+    }
+    if (!env.REVEALUI_LICENSE_PUBLIC_KEY) {
+        throw new Error('LICENSE VALIDATION FAILED: REVEALUI_LICENSE_PUBLIC_KEY is required for RevForge deployments. ' +
+            'Stamped kits embed this value in docker/.env.example; check that it survived the bootstrap step.');
+    }
+    // Restore real newlines if the public key landed as a single-line PEM
+    // (stamp.sh .env encoding). Split/join, no authored regex — mirrors
+    // @revealui/core/license normalizePem. GAP-259 P0-4.
+    const publicKey = env.REVEALUI_LICENSE_PUBLIC_KEY.split('\\n').join('\n');
+    const expectedCustomerId = env.REVEALUI_LICENSED_CUSTOMER_ID || undefined;
+    const payload = await validateLicenseKey(env.REVEALUI_LICENSE_KEY, publicKey, expectedCustomerId);
+    if (!payload) {
+        const tokenKid = decodeJwtKid(env.REVEALUI_LICENSE_KEY);
+        if (tokenKid !== undefined) {
+            const expectedKid = await computeKeyId(publicKey);
+            if (tokenKid !== expectedKid) {
+                throw new Error('LICENSE VALIDATION FAILED: REVEALUI_LICENSE_PUBLIC_KEY does not match the key that ' +
+                    `signed REVEALUI_LICENSE_KEY (license key id "${tokenKid}", configured public key id ` +
+                    `"${expectedKid}"). The stamped kit baked the wrong public key. Re-issue the license ` +
+                    'with the matching keypair, or bake the public key that pairs with the signing key, ' +
+                    'then re-run bin/revvault-bootstrap.sh. Contact the operator who stamped this kit.');
+            }
+        }
+        throw new Error('LICENSE VALIDATION FAILED: REVEALUI_LICENSE_KEY is invalid, expired beyond grace, ' +
+            'signed with a key that does not match REVEALUI_LICENSE_PUBLIC_KEY, or its ' +
+            'customerId does not match REVEALUI_LICENSED_CUSTOMER_ID (if set). ' +
+            'Contact the operator who stamped this kit to re-issue the license.');
+    }
+    if (payload.domains && payload.domains.length > 0) {
+        const publicUrl = (env.REVEALUI_PUBLIC_SERVER_URL ?? env.NEXT_PUBLIC_SERVER_URL ?? '').trim();
+        if (publicUrl) {
+            let host = '';
+            try {
+                host = new URL(publicUrl).hostname;
+            }
+            catch {
+                host = '';
+            }
+            if (!hostMatchesLicensedDomains(host, payload.domains)) {
+                throw new Error('LICENSE VALIDATION FAILED: this license is restricted to ' +
+                    `[${payload.domains.join(', ')}], but REVEALUI_PUBLIC_SERVER_URL host ` +
+                    `"${host || '(unparseable)'}" is not among them. Set REVEALUI_PUBLIC_SERVER_URL ` +
+                    'to a licensed domain, or contact the operator who stamped this kit.');
+            }
+        }
+    }
+}

package/dist/storage/_sigv4.d.ts

@@ -45,9 +45,11 @@ export interface SigV4Result {
  * key → signature. Verified against AWS's official `get-vanilla` test vector.
  */
 export declare function computeSigV4(input: CanonicalInput): SigV4Result;
+/** Payload hash token for presigned URLs (body hash unknown at sign time). */
+export declare const UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
 /** Inputs for an R2/S3 request signature. */
 export interface SignS3Input {
-    method: 'GET' | 'PUT' | 'DELETE';
+    method: 'GET' | 'PUT' | 'DELETE' | 'HEAD';
     accountId: string;
     bucket: string;
     /** Object key; omit for bucket-level operations (e.g. ListObjectsV2). */
@@ -73,4 +75,36 @@ export interface SignedS3Request {
  * from the URL (same value), and `Host` is a forbidden header to set manually.
  */
 export declare function signS3Request(input: SignS3Input): SignedS3Request;
+/** Inputs for a query-string presigned S3/R2 URL (no Authorization header). */
+export interface SignS3PresignedInput {
+    method: 'GET' | 'PUT' | 'DELETE' | 'HEAD';
+    accountId: string;
+    bucket: string;
+    key: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Lifetime of the URL in seconds. */
+    expiresInSeconds: number;
+    /**
+     * Headers the client must send and that are included in the signature
+     * (content-type, content-length, …). Host is always signed and omitted
+     * from the returned headers (fetch sets it from the URL).
+     */
+    signedHeaders?: Record<string, string>;
+    now: Date;
+}
+export interface PresignedS3Url {
+    url: string;
+    /** Headers the client must include (signed set minus host). */
+    headers: Record<string, string>;
+}
+/**
+ * Build a query-string SigV4 presigned URL for R2/S3.
+ *
+ * Uses UNSIGNED-PAYLOAD so the client does not need to pre-hash the body.
+ * Credential and signature ride in the query string; the client sends only
+ * the signed non-host headers (e.g. content-type) with the request.
+ */
+export declare function signS3PresignedUrl(input: SignS3PresignedInput): PresignedS3Url;
 //# sourceMappingURL=_sigv4.d.ts.map

package/dist/storage/_sigv4.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_sigv4.d.ts","sourceRoot":"","sources":["../../src/storage/_sigv4.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,iFAAiF;AACjF,eAAO,MAAM,YAAY,qEAAqE,CAAC;AAE/F,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAE3D;AAQD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,MAAM,CAaxE;AAQD,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC1B,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CAkC/D;AAED,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,GAAG,EAAE,IAAI,CAAC;CACX;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,eAAe,CAmDjE"}
+{"version":3,"file":"_sigv4.d.ts","sourceRoot":"","sources":["../../src/storage/_sigv4.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,iFAAiF;AACjF,eAAO,MAAM,YAAY,qEAAqE,CAAC;AAE/F,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAE3D;AAQD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,MAAM,CAaxE;AAQD,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC1B,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CAkC/D;AAED,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,GAAG,EAAE,IAAI,CAAC;CACX;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,eAAe,CAmDjE;AAED,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,GAAG,EAAE,IAAI,CAAC;CACX;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,oBAAoB,GAAG,cAAc,CAgD9E"}

package/dist/storage/_sigv4.js

@@ -81,6 +81,8 @@ export function computeSigV4(input) {
     const signature = createHmac('sha256', kSigning).update(stringToSign, 'utf8').digest('hex');
     return { signature, signedHeaders, scope, canonicalQuery };
 }
+/** Payload hash token for presigned URLs (body hash unknown at sign time). */
+export const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD';
 /**
  * Build a signed R2 request: a path-style URL + AWS4-HMAC-SHA256 Authorization
  * header. The `host` header is signed but not returned — fetch/undici sets it
@@ -132,3 +134,54 @@ export function signS3Request(input) {
     const url = `https://${host}${canonicalPath}${canonicalQuery ? `?${canonicalQuery}` : ''}`;
     return { url, headers };
 }
+/**
+ * Build a query-string SigV4 presigned URL for R2/S3.
+ *
+ * Uses UNSIGNED-PAYLOAD so the client does not need to pre-hash the body.
+ * Credential and signature ride in the query string; the client sends only
+ * the signed non-host headers (e.g. content-type) with the request.
+ */
+export function signS3PresignedUrl(input) {
+    const host = `${input.accountId}.r2.cloudflarestorage.com`;
+    const { amzDate, dateStamp } = toAmzDate(input.now);
+    const scope = `${dateStamp}/${input.region}/${S3_SERVICE}/aws4_request`;
+    const encodedKey = input.key
+        .split('/')
+        .map((segment) => awsUriEncode(segment, false))
+        .join('/');
+    const canonicalPath = `/${awsUriEncode(input.bucket, false)}/${encodedKey}`;
+    const clientHeaders = {};
+    const headersToSign = { host };
+    for (const [name, value] of Object.entries(input.signedHeaders ?? {})) {
+        const lower = name.toLowerCase();
+        if (lower === 'host')
+            continue;
+        headersToSign[lower] = value;
+        clientHeaders[lower] = value;
+    }
+    const signedHeaderNames = Object.keys(headersToSign).sort().join(';');
+    const query = [
+        ['X-Amz-Algorithm', ALGORITHM],
+        ['X-Amz-Credential', `${input.accessKeyId}/${scope}`],
+        ['X-Amz-Date', amzDate],
+        ['X-Amz-Expires', String(input.expiresInSeconds)],
+        ['X-Amz-SignedHeaders', signedHeaderNames],
+    ];
+    const { signature, canonicalQuery } = computeSigV4({
+        method: input.method,
+        canonicalPath,
+        query,
+        headersToSign,
+        payloadHash: UNSIGNED_PAYLOAD,
+        amzDate,
+        region: input.region,
+        service: S3_SERVICE,
+        accessKeyId: input.accessKeyId,
+        secretAccessKey: input.secretAccessKey,
+    });
+    const fullQuery = `${canonicalQuery}&${awsUriEncode('X-Amz-Signature', true)}=${awsUriEncode(signature, true)}`;
+    return {
+        url: `https://${host}${canonicalPath}?${fullQuery}`,
+        headers: clientHeaders,
+    };
+}

package/dist/storage/index.d.ts

@@ -3,7 +3,7 @@ export { createMockProvider } from './mock.js';
 export type { ObjectStorageConfig } from './object-storage.js';
 export { objectStorage } from './object-storage.js';
 export { createR2Provider } from './r2.js';
-export type { ListItem, ListOptions, ListResult, PutOptions, PutResult, R2Config, StorageConfig, StorageProvider, } from './types.js';
+export type { HeadObjectResult, ListItem, ListOptions, ListResult, PresignPutOptions, PresignPutResult, PutOptions, PutResult, R2Config, StorageConfig, StorageProvider, } from './types.js';
 /**
  * Construct a StorageProvider from a tagged config.
  *

package/dist/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAK/D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC3C,YAAY,EACV,QAAQ,EACR,WAAW,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,QAAQ,EACR,aAAa,EACb,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAcpE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAK/D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC3C,YAAY,EACV,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,QAAQ,EACR,aAAa,EACb,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAcpE"}

package/dist/storage/index.js

@@ -3,9 +3,8 @@
 //
 // Phase 1 (#959): types.ts + index.ts type re-exports.
 // Phase 2a (#959 follow-up): r2 + mock providers + createStorage factory.
-// Phase 2b (#959 follow-up): apps/server media-route cutover onto R2.
-// #1644: legacy Vercel Blob StorageProvider removed once R2 was confirmed in
-//   every production environment — R2 is now the sole non-mock backend.
+// Phase 2b media-route cutover onto R2 (server) + #1644 Vercel Blob removal.
+// Phase 2b presign (GAP-215): createPresignedPutUrl + headObject + getObjectRange.
 import { createMockProvider } from './mock.js';
 import { createR2Provider } from './r2.js';
 export { createMockProvider } from './mock.js';

package/dist/storage/mock.d.ts

@@ -8,9 +8,9 @@
  * `mock://` scheme so callers can distinguish mock results from real ones
  * without parsing host names.
  *
- * GAP-208 Phase 2a (2026-05-18).
+ * GAP-208 Phase 2a (2026-05-18). Phase 2b (GAP-215): presigned PUT + head + range.
  */
-import type { ListOptions, ListResult, PutOptions, PutResult, StorageProvider } from './types.js';
+import type { HeadObjectResult, ListOptions, ListResult, PresignPutOptions, PresignPutResult, PutOptions, PutResult, StorageProvider } from './types.js';
 interface MockEntry {
     body: Uint8Array;
     contentType: string;
@@ -22,6 +22,9 @@ declare class MockProvider implements StorageProvider {
     readonly provider = "mock";
     private readonly store;
     put(key: string, data: Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>, opts?: PutOptions): Promise<PutResult>;
+    createPresignedPutUrl(opts: PresignPutOptions): Promise<PresignPutResult>;
+    headObject(key: string): Promise<HeadObjectResult>;
+    getObjectRange(key: string, start: number, endInclusive: number): Promise<Uint8Array>;
     del(keyOrUrl: string): Promise<void>;
     list(opts?: ListOptions): Promise<ListResult>;
     /** Test helper — read the raw bytes back. Not part of StorageProvider. */

package/dist/storage/mock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../src/storage/mock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAEV,WAAW,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,eAAe,EAChB,MAAM,YAAY,CAAC;AAMpB,UAAU,SAAS;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,UAAU,EAAE,IAAI,CAAC;CAClB;AAED,cAAM,YAAa,YAAW,eAAe;IAC3C,QAAQ,CAAC,QAAQ,UAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IAEhD,GAAG,CACP,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,IAAI,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,EAClE,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,SAAS,CAAC;IAiBf,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpC,IAAI,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAgCnD,0EAA0E;IAC1E,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIzC,wEAAwE;IACxE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI3C,0EAA0E;IAC1E,IAAI,IAAI,MAAM;IAId,0EAA0E;IAC1E,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,UAAU;CAMnB;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAEjD;AAED,YAAY,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../src/storage/mock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EACV,gBAAgB,EAEhB,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,eAAe,EAChB,MAAM,YAAY,CAAC;AAOpB,UAAU,SAAS;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,UAAU,EAAE,IAAI,CAAC;CAClB;AAED,cAAM,YAAa,YAAW,eAAe;IAC3C,QAAQ,CAAC,QAAQ,UAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IAEhD,GAAG,CACP,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,IAAI,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,EAClE,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,SAAS,CAAC;IAiBf,qBAAqB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA6BzE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAYlD,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAkBrF,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpC,IAAI,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAgCnD,0EAA0E;IAC1E,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIzC,wEAAwE;IACxE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI3C,0EAA0E;IAC1E,IAAI,IAAI,MAAM;IAId,0EAA0E;IAC1E,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,UAAU;CAMnB;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAEjD;AAED,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/dist/storage/mock.js

@@ -8,12 +8,13 @@
  * `mock://` scheme so callers can distinguish mock results from real ones
  * without parsing host names.
  *
- * GAP-208 Phase 2a (2026-05-18).
+ * GAP-208 Phase 2a (2026-05-18). Phase 2b (GAP-215): presigned PUT + head + range.
  */
 import { toUint8Array } from './_helpers.js';
 const PROVIDER_TAG = 'mock';
 const MOCK_URL_SCHEME = 'mock://storage';
 const DEFAULT_LIST_LIMIT = 1000;
+const DEFAULT_PRESIGN_EXPIRES_SECONDS = 900;
 class MockProvider {
     provider = PROVIDER_TAG;
     store = new Map();
@@ -33,6 +34,58 @@ class MockProvider {
             provider: PROVIDER_TAG,
         };
     }
+    async createPresignedPutUrl(opts) {
+        const expiresInSeconds = opts.expiresInSeconds ?? DEFAULT_PRESIGN_EXPIRES_SECONDS;
+        if (expiresInSeconds <= 0) {
+            throw new Error('createPresignedPutUrl: expiresInSeconds must be positive');
+        }
+        const now = new Date();
+        const expiresAt = new Date(now.getTime() + expiresInSeconds * 1000);
+        const headers = {
+            'content-type': opts.contentType,
+        };
+        if (opts.contentLength !== undefined) {
+            headers['content-length'] = String(opts.contentLength);
+        }
+        // Synthetic presigned URL. Tests that exercise the full client flow call
+        // put() with the same key after "uploading"; route tests mock this method.
+        const params = new URLSearchParams({
+            expires: String(Math.floor(expiresAt.getTime() / 1000)),
+            'content-type': opts.contentType,
+        });
+        return {
+            url: `${MOCK_URL_SCHEME}/presign/${opts.key}?${params.toString()}`,
+            headers,
+            key: opts.key,
+            expiresAt,
+        };
+    }
+    async headObject(key) {
+        const entry = this.store.get(key);
+        if (!entry) {
+            throw new Error(`mock HEAD failed for "${key}": NoSuchKey object not found`);
+        }
+        return {
+            size: entry.body.byteLength,
+            contentType: entry.contentType,
+            url: `${MOCK_URL_SCHEME}/${key}`,
+        };
+    }
+    async getObjectRange(key, start, endInclusive) {
+        if (start < 0 || endInclusive < start) {
+            throw new Error(`getObjectRange: invalid range ${start}-${endInclusive} (start must be >= 0 and endInclusive >= start)`);
+        }
+        const entry = this.store.get(key);
+        if (!entry) {
+            throw new Error(`mock GET range failed for "${key}": NoSuchKey object not found`);
+        }
+        // Inclusive end, clamped to body length (mirrors S3 range semantics).
+        const end = Math.min(endInclusive, entry.body.byteLength - 1);
+        if (start >= entry.body.byteLength) {
+            return new Uint8Array(0);
+        }
+        return entry.body.slice(start, end + 1);
+    }
     async del(keyOrUrl) {
         const key = this.extractKey(keyOrUrl);
         this.store.delete(key);

package/dist/storage/r2.d.ts

@@ -12,13 +12,15 @@
  *
  * GAP-208 Phase 2a (2026-05-18). Phase 1 (interface + types) shipped in #959.
  * Native client (dropping @aws-sdk/client-s3) landed 2026-06-09.
+ * Phase 2b (GAP-215): createPresignedPutUrl + headObject + getObjectRange for
+ * direct-to-R2 media uploads.
  *
  * Server-only. Do NOT import from client-side code or edge runtime.
  *
- * Known limitation (unchanged from the SDK version): request bodies are
- * buffered fully in memory (see toUint8Array) so the payload can be hashed for
- * SigV4. Streaming uploads (STREAMING-AWS4-HMAC-SHA256-PAYLOAD) are a future
- * enhancement; presigned/private URLs remain Phase 2b.
+ * Known limitation: request bodies for server-side put() are buffered fully in
+ * memory (see toUint8Array) so the payload can be hashed for SigV4. Streaming
+ * uploads (STREAMING-AWS4-HMAC-SHA256-PAYLOAD) are a future enhancement.
+ * Direct client uploads use createPresignedPutUrl and never buffer in the API.
  */
 import type { R2Config, StorageProvider } from './types.js';
 export declare function createR2Provider(config: R2Config): StorageProvider;

package/dist/storage/r2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"r2.d.ts","sourceRoot":"","sources":["../../src/storage/r2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,KAAK,EAMV,QAAQ,EACR,eAAe,EAChB,MAAM,YAAY,CAAC;AAkKpB,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,eAAe,CAElE"}
+{"version":3,"file":"r2.d.ts","sourceRoot":"","sources":["../../src/storage/r2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,KAAK,EASV,QAAQ,EACR,eAAe,EAChB,MAAM,YAAY,CAAC;AA6QpB,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,eAAe,CAElE"}

package/dist/storage/r2.js

@@ -12,20 +12,23 @@
  *
  * GAP-208 Phase 2a (2026-05-18). Phase 1 (interface + types) shipped in #959.
  * Native client (dropping @aws-sdk/client-s3) landed 2026-06-09.
+ * Phase 2b (GAP-215): createPresignedPutUrl + headObject + getObjectRange for
+ * direct-to-R2 media uploads.
  *
  * Server-only. Do NOT import from client-side code or edge runtime.
  *
- * Known limitation (unchanged from the SDK version): request bodies are
- * buffered fully in memory (see toUint8Array) so the payload can be hashed for
- * SigV4. Streaming uploads (STREAMING-AWS4-HMAC-SHA256-PAYLOAD) are a future
- * enhancement; presigned/private URLs remain Phase 2b.
+ * Known limitation: request bodies for server-side put() are buffered fully in
+ * memory (see toUint8Array) so the payload can be hashed for SigV4. Streaming
+ * uploads (STREAMING-AWS4-HMAC-SHA256-PAYLOAD) are a future enhancement.
+ * Direct client uploads use createPresignedPutUrl and never buffer in the API.
  */
 import { toUint8Array } from './_helpers.js';
-import { EMPTY_SHA256, sha256Hex, signS3Request } from './_sigv4.js';
+import { EMPTY_SHA256, sha256Hex, signS3PresignedUrl, signS3Request } from './_sigv4.js';
 import { parseListObjectsV2, s3ErrorFields } from './_xml.js';
 const PROVIDER_TAG = 'r2';
 const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
 const DEFAULT_LIST_LIMIT = 1000;
+const DEFAULT_PRESIGN_EXPIRES_SECONDS = 900;
 const REGION = 'auto';
 class R2Provider {
     provider = PROVIDER_TAG;
@@ -36,9 +39,9 @@ class R2Provider {
     publicBaseUrl;
     constructor(config) {
         if (!config.publicBaseUrl) {
-            throw new Error('R2 provider requires R2Config.publicBaseUrl. Presigned/private URLs ' +
-                'are not supported in Phase 2a. Set publicBaseUrl to either a bound ' +
-                "custom domain (e.g. 'https://media.revealui.com') or the R2 dev URL " +
+            throw new Error('R2 provider requires R2Config.publicBaseUrl for public media URLs after ' +
+                'upload. Set publicBaseUrl to either a bound custom domain ' +
+                "(e.g. 'https://media.revealui.com') or the R2 dev URL " +
                 "('https://<account-id>.r2.cloudflarestorage.com/<bucket>').");
         }
         this.accountId = config.accountId;
@@ -49,9 +52,9 @@ class R2Provider {
     }
     async put(key, data, opts) {
         if (opts?.access === 'private') {
-            throw new Error("R2 provider Phase 2a does not support access: 'private'. All objects " +
-                'are written under the publicBaseUrl. Presigned/private-URL support ' +
-                'lands in Phase 2b.');
+            throw new Error("R2 provider does not support access: 'private' for put(). Use " +
+                'createPresignedPutUrl for client direct uploads; public object URLs ' +
+                'still use publicBaseUrl after confirm.');
         }
         const body = await toUint8Array(data);
         const extraHeaders = {
@@ -90,11 +93,99 @@ class R2Provider {
         }
         return {
             key,
-            url: `${this.publicBaseUrl}/${key}`,
+            url: this.objectPublicUrl(key),
             size: body.byteLength,
             provider: PROVIDER_TAG,
         };
     }
+    async createPresignedPutUrl(opts) {
+        const expiresInSeconds = opts.expiresInSeconds ?? DEFAULT_PRESIGN_EXPIRES_SECONDS;
+        if (expiresInSeconds <= 0) {
+            throw new Error('createPresignedPutUrl: expiresInSeconds must be positive');
+        }
+        const signedHeaders = {
+            'content-type': opts.contentType,
+        };
+        if (opts.contentLength !== undefined) {
+            signedHeaders['content-length'] = String(opts.contentLength);
+        }
+        const now = new Date();
+        const { url, headers } = signS3PresignedUrl({
+            method: 'PUT',
+            accountId: this.accountId,
+            bucket: this.bucket,
+            key: opts.key,
+            region: REGION,
+            accessKeyId: this.accessKeyId,
+            secretAccessKey: this.secretAccessKey,
+            expiresInSeconds,
+            signedHeaders,
+            now,
+        });
+        return {
+            url,
+            headers,
+            key: opts.key,
+            expiresAt: new Date(now.getTime() + expiresInSeconds * 1000),
+        };
+    }
+    async headObject(key) {
+        const { url, headers } = signS3Request({
+            method: 'HEAD',
+            accountId: this.accountId,
+            bucket: this.bucket,
+            key,
+            region: REGION,
+            accessKeyId: this.accessKeyId,
+            secretAccessKey: this.secretAccessKey,
+            payloadHash: EMPTY_SHA256,
+            now: new Date(),
+        });
+        const response = await fetch(url, { method: 'HEAD', headers });
+        if (response.status === 404) {
+            throw new Error(`R2 HEAD failed for "${key}": NoSuchKey object not found`);
+        }
+        if (!response.ok) {
+            throw await storageError('HEAD', key, response);
+        }
+        const lengthHeader = response.headers.get('content-length');
+        const size = lengthHeader === null ? 0 : Number(lengthHeader);
+        if (!Number.isFinite(size) || size < 0) {
+            throw new Error(`R2 HEAD failed for "${key}": invalid content-length`);
+        }
+        return {
+            size,
+            contentType: response.headers.get('content-type') ?? DEFAULT_CONTENT_TYPE,
+            url: this.objectPublicUrl(key),
+        };
+    }
+    async getObjectRange(key, start, endInclusive) {
+        if (start < 0 || endInclusive < start) {
+            throw new Error(`getObjectRange: invalid range ${start}-${endInclusive} (start must be >= 0 and endInclusive >= start)`);
+        }
+        const { url, headers } = signS3Request({
+            method: 'GET',
+            accountId: this.accountId,
+            bucket: this.bucket,
+            key,
+            region: REGION,
+            accessKeyId: this.accessKeyId,
+            secretAccessKey: this.secretAccessKey,
+            payloadHash: EMPTY_SHA256,
+            extraHeaders: { range: `bytes=${start}-${endInclusive}` },
+            now: new Date(),
+        });
+        const response = await fetch(url, { method: 'GET', headers });
+        if (response.status === 404) {
+            throw new Error(`R2 GET range failed for "${key}": NoSuchKey object not found`);
+        }
+        // 206 Partial Content is the expected success; some backends return 200
+        // with the full object when range is unsupported — still accept it.
+        if (!response.ok && response.status !== 206) {
+            throw await storageError('GET range', key, response);
+        }
+        return new Uint8Array(await response.arrayBuffer());
+    }
     async del(keyOrUrl) {
         const key = this.extractKey(keyOrUrl);
         const { url, headers } = signS3Request({
@@ -139,7 +230,7 @@ class R2Provider {
         const parsed = parseListObjectsV2(await response.text());
         const items = parsed.objects.map((entry) => ({
             key: entry.key,
-            url: `${this.publicBaseUrl}/${entry.key}`,
+            url: this.objectPublicUrl(entry.key),
             size: entry.size,
             uploadedAt: entry.lastModified,
         }));
@@ -149,6 +240,9 @@ class R2Provider {
             hasMore: parsed.isTruncated,
         };
     }
+    objectPublicUrl(key) {
+        return `${this.publicBaseUrl}/${key}`;
+    }
     extractKey(keyOrUrl) {
         const parsed = tryParseUrl(keyOrUrl);
         if (!parsed) {

package/dist/storage/types.d.ts

@@ -20,9 +20,58 @@ export interface StorageProvider {
     del(keyOrUrl: string): Promise<void>;
     /** List items, optionally filtered by key prefix. Used by health probes + admin browsing. */
     list(opts?: ListOptions): Promise<ListResult>;
+    /**
+     * Issue a short-lived presigned PUT URL so clients upload bytes direct to the
+     * backend (GAP-215 / Phase 2b). File bytes never buffer in the API function.
+     */
+    createPresignedPutUrl(opts: PresignPutOptions): Promise<PresignPutResult>;
+    /**
+     * HEAD an object. Used by the media confirm endpoint to re-check size and
+     * content-type after a direct-to-storage upload.
+     */
+    headObject(key: string): Promise<HeadObjectResult>;
+    /**
+     * GET a byte range of an object (inclusive end). Used to re-check magic
+     * bytes on confirm without downloading the whole file.
+     */
+    getObjectRange(key: string, start: number, endInclusive: number): Promise<Uint8Array>;
     /** Provider tag (e.g. "r2", "mock") — exposed so consumers can adapt URL handling. */
     readonly provider: string;
 }
+export interface PresignPutOptions {
+    /** Storage key the client will write (provider-relative, e.g. "media/uuid.jpg"). */
+    key: string;
+    /** MIME type the client must send as Content-Type (signed into the URL). */
+    contentType: string;
+    /**
+     * Optional declared Content-Length. When set, signed into the request so the
+     * client cannot upload a larger body. Browser fetch cannot set Content-Length
+     * manually, so media direct-upload leaves this unset and re-checks size via
+     * headObject on confirm.
+     */
+    contentLength?: number;
+    /** URL lifetime in seconds. Defaults to provider-specific value (typically 900). */
+    expiresInSeconds?: number;
+}
+export interface PresignPutResult {
+    /** Fully-qualified presigned PUT URL (query-string SigV4). */
+    url: string;
+    /**
+     * Headers the client MUST send with the PUT (at least content-type). Values
+     * are already signed into the URL's X-Amz-SignedHeaders set.
+     */
+    headers: Record<string, string>;
+    /** Storage key the URL writes to (echo of PresignPutOptions.key). */
+    key: string;
+    /** Absolute expiry of the URL. */
+    expiresAt: Date;
+}
+export interface HeadObjectResult {
+    size: number;
+    contentType: string;
+    /** Public (or mock) URL the object is reachable at for GET. */
+    url: string;
+}
 export interface PutOptions {
     /** MIME type — written to the object's Content-Type header. Defaults to "application/octet-stream". */
     contentType?: string;
@@ -93,10 +142,11 @@ export interface R2Config {
     /** Bucket name (per-account-globally-unique within R2). */
     bucket: string;
     /**
-     * Optional public base URL for objects (e.g. "https://media.revealui.com" if a
-     * custom domain is bound, or "https://<account-id>.r2.cloudflarestorage.com/<bucket>"
-     * for the dev URL). When set, PutResult.url uses this base. When omitted, PutResult.url
-     * falls back to a presigned URL (private bucket pattern).
+     * Public base URL for objects (e.g. "https://media.revealui.com" if a custom
+     * domain is bound, or the R2 dev URL). Required: PutResult.url, HeadObjectResult.url,
+     * and media rows after confirm use this base. Presigned PUT URLs themselves
+     * target the S3 API endpoint and do not need this, but the final public media
+     * URL still does.
      */
     publicBaseUrl?: string;
 }