fix(plugin-sharing): share-link public answers are not cached, the password header passes CORS, and hashing works in WebContainer

- X-Share-Password joins DEFAULT_CORS_ALLOW_HEADERS so a cross-origin client
  can use the header form.
- Both public share-link routes answer Cache-Control: no-store and
  Vary: X-Share-Password on every outcome, on both mounts.
- On WebContainer the password key is derived by @noble/hashes scrypt with
  the same parameters and stored form as node:crypto; hashes interchange.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018zT8d8NpiQ1ExhuNd5TxY6

Author: claude

.changeset/21839-share-link-password-handling.md

@@ -1,9 +1,14 @@
 ---
 '@objectstack/plugin-sharing': patch
+'@objectstack/plugin-hono-server': patch
+'@objectstack/runtime': patch
 ---
 
 Share-link passwords follow the platform's credential rules (#21839).
 
 - **The stored hash never leaves the server.** The share-link mint response (`POST /api/v1/share-links`, and `ShareLinkService.createLink`'s return value) no longer carries `password_hash`. The list and the redemption result are projected the same way. A client that reads a link's password state keeps reading it from the redemption route's `NEEDS_PASSWORD` answer, as before.
 - **The stored form is the platform's slow password hash.** New passwords are hashed with scrypt at the parameters account passwords use, instead of one salted SHA-256. Links minted before this release keep working: a stored password in a legacy form still verifies, and it is re-hashed into the new form on its first successful redemption. Every comparison is constant-time. A deployment that injects its own `hashPassword` / `verifyPassword` pair is unaffected, and its stored forms are left alone.
 - **The password travels in a header.** Both public share-link routes (`GET /api/v1/share-links/:token/resolve` and `/:token/messages`) accept the `x-share-password` request header, the preferred form, because a header is not part of the request URL. The `?password=` query parameter is still accepted for compatibility, so current consoles keep working until they move to the header. `/messages` accepted only the query parameter on this mount before.
+- **Cross-origin clients can send the header.** `X-Share-Password` is in the default CORS preflight allow-list (`DEFAULT_CORS_ALLOW_HEADERS` in `@objectstack/plugin-hono-server`, which the `@objectstack/hono` adapter also applies). A deployment that passes its own `allowHeaders` is unchanged; add the header to that list to let a cross-origin client use it.
+- **Public share-link answers are not cached.** Both public routes answer with `Cache-Control: no-store` and `Vary: X-Share-Password` on every outcome, on both mounts (the sharing plugin's routes and the runtime dispatcher's `/share-links` domain). The authenticated create, list and revoke routes are unchanged.
+- **Hashing works in WebContainer.** On StackBlitz WebContainer, where `node:crypto.scrypt` is incomplete, the password is hashed with the pure-JS scrypt from `@noble/hashes` (now a dependency of `@objectstack/plugin-sharing`, as it already is of `@objectstack/plugin-auth`), at the same parameters and in the same stored form. A hash made on either runtime verifies on the other.

content/docs/protocol/kernel/http-protocol.mdx

@@ -999,18 +999,19 @@ ObjectStack sends CORS headers automatically:
 ```http
 Access-Control-Allow-Origin: https://app.acme.com
 Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
-Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With, X-Tenant-ID, X-Environment-Id, If-Match
+Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With, X-Tenant-ID, X-Environment-Id, If-Match, X-Share-Password
 Access-Control-Expose-Headers: set-auth-token, x-objectstack-dropped-fields
 Access-Control-Max-Age: 86400
 ```
 
-Three of the allowed request headers are easy to overlook, and each one disables
+Four of the allowed request headers are easy to overlook, and each one disables
 a feature if an intermediate proxy strips it:
 
 | Header | Why it is allowed |
 | --- | --- |
 | `X-Tenant-ID` / `X-Environment-Id` | Route the request to its environment on a multi-tenant host. |
 | `If-Match` | Carries the OCC token on record `PATCH`es. Without it, a cross-origin save fails in the browser with "Failed to fetch". |
+| `X-Share-Password` | Carries a share-link password to the public `/share-links/:token/resolve` and `/messages` routes. It is the preferred form because a header stays out of URLs; without it, a cross-origin client can only send the password as a query parameter. |
 
 The two **exposed** response headers matter to browser clients specifically:
 `set-auth-token` delivers a rotated session token (without it a cross-origin

packages/plugins/plugin-hono-server/src/adapter.ts

@@ -64,6 +64,10 @@ import {
  * `If-Match` carries the OCC token on record PATCHes (objectui's inline edit,
  * REST `update` with `ifMatch`) — without it in the preflight allow-list every
  * cross-origin save fails in the browser with "Failed to fetch" (objectui#2572).
+ * `X-Share-Password` carries a share-link password to the public
+ * `/share-links/:token/resolve` and `/messages` routes — the preferred form,
+ * since a header stays out of URLs (#21839); without it here a cross-origin
+ * client could only use the query-parameter form.
  */
 export const DEFAULT_CORS_ALLOW_HEADERS: readonly string[] = Object.freeze([
     'Content-Type',
@@ -72,6 +76,7 @@ export const DEFAULT_CORS_ALLOW_HEADERS: readonly string[] = Object.freeze([
     'X-Tenant-ID',
     'X-Environment-Id',
     'If-Match',
+    'X-Share-Password',
 ]);
 
 /**

packages/plugins/plugin-hono-server/src/hono-plugin.test.ts

@@ -313,6 +313,17 @@ describe('HonoServerPlugin', () => {
             expect(corsConfigCapture.last.allowHeaders).toContain('If-Match');
         });
 
+        it('should allow X-Share-Password by default (share-link password header, #21839)', async () => {
+            corsConfigCapture.last = undefined;
+
+            const plugin = new HonoServerPlugin();
+            await plugin.init(context as PluginContext);
+
+            // The header form keeps the password out of URLs; a preflight that
+            // does not allow it leaves a cross-origin client only the query form.
+            expect(corsConfigCapture.last.allowHeaders).toContain('X-Share-Password');
+        });
+
         it('should merge user-supplied exposeHeaders with set-auth-token default', async () => {
             corsConfigCapture.last = undefined;
 

packages/plugins/plugin-sharing/package.json

@@ -20,6 +20,7 @@
     "gen:test-typecheck-debt": "tsx ../../../scripts/check-test-typecheck.mts --update --package packages/plugins/plugin-sharing --project tsconfig.test.json"
   },
   "dependencies": {
+    "@noble/hashes": "^2.4.0",
     "@objectstack/core": "workspace:*",
     "@objectstack/formula": "workspace:*",
     "@objectstack/metadata-core": "workspace:*",

packages/plugins/plugin-sharing/src/share-link-password-webcontainer.test.ts

@@ -0,0 +1,81 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#21839] On WebContainer the share-link password is hashed by the pure-JS
+ * scrypt (`@noble/hashes`), because that host's `node:crypto.scrypt` is
+ * incomplete; everywhere else by `node:crypto`. The two must be one hash.
+ *
+ * Pinned:
+ *  - with a WebContainer signal set, `node:crypto.scrypt` is never called —
+ *    the pure-JS path really ran;
+ *  - without one, it is — the native path really ran;
+ *  - a hash minted on either path verifies on the other, and a wrong password
+ *    is refused on both;
+ *  - the two paths derive byte-identical keys for the same password and salt
+ *    (compared directly against `node:crypto`).
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import * as nodeCrypto from 'node:crypto';
+import { hashShareLinkPassword, verifyShareLinkPassword } from './share-link-password.js';
+
+vi.mock('node:crypto', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:crypto')>();
+  return { ...actual, scrypt: vi.fn(actual.scrypt) };
+});
+
+const PASSWORD = 'Ünïcödé pass 21839';
+const nodeScrypt = vi.mocked(nodeCrypto.scrypt);
+
+function onWebContainer(on: boolean) {
+  vi.stubEnv('STACKBLITZ', on ? '1' : '');
+  vi.stubEnv('SHELL', on ? '/bin/jsh' : '/bin/bash');
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  nodeScrypt.mockClear();
+});
+
+describe('[#21839] share-link password: node:crypto and pure-JS scrypt are interchangeable', () => {
+  it('the WebContainer path does not touch node:crypto.scrypt; the native path does', async () => {
+    onWebContainer(true);
+    await hashShareLinkPassword(PASSWORD);
+    expect(nodeScrypt).not.toHaveBeenCalled();
+
+    onWebContainer(false);
+    await hashShareLinkPassword(PASSWORD);
+    expect(nodeScrypt).toHaveBeenCalledTimes(1);
+  });
+
+  it('a hash minted on WebContainer verifies natively, and the reverse', async () => {
+    onWebContainer(true);
+    const pureJsHash = await hashShareLinkPassword(PASSWORD);
+    onWebContainer(false);
+    const nativeHash = await hashShareLinkPassword(PASSWORD);
+
+    expect(pureJsHash).toMatch(/^scrypt\$[0-9a-f]{32}\$[0-9a-f]{128}$/);
+    expect(nativeHash).toMatch(/^scrypt\$[0-9a-f]{32}\$[0-9a-f]{128}$/);
+
+    onWebContainer(false);
+    expect(await verifyShareLinkPassword(PASSWORD, pureJsHash)).toBe(true);
+    expect(await verifyShareLinkPassword('wrong 21839', pureJsHash)).toBe(false);
+    expect(nodeScrypt).toHaveBeenCalled();
+
+    onWebContainer(true);
+    nodeScrypt.mockClear();
+    expect(await verifyShareLinkPassword(PASSWORD, nativeHash)).toBe(true);
+    expect(await verifyShareLinkPassword('wrong 21839', nativeHash)).toBe(false);
+    expect(nodeScrypt).not.toHaveBeenCalled();
+  });
+
+  it('the pure-JS key is byte-identical to node:crypto for the same password and salt', async () => {
+    onWebContainer(true);
+    const hash = await hashShareLinkPassword(PASSWORD);
+    const [, saltHex, keyHex] = hash.split('$');
+    const expected = nodeCrypto
+      .scryptSync(PASSWORD.normalize('NFKC'), saltHex!, 64, { N: 16384, r: 16, p: 1, maxmem: 128 * 16384 * 16 * 2 })
+      .toString('hex');
+    expect(keyHex).toBe(expected);
+  });
+});

packages/plugins/plugin-sharing/src/share-link-password.test.ts

@@ -22,7 +22,12 @@
  *  - the `x-share-password` header is accepted on both public routes, the
  *    `?password=` query parameter still is, and a wrong password is refused
  *    through either form;
- *  - no log line carries the presented password.
+ *  - no log line carries the presented password;
+ *  - both public routes answer `Cache-Control: no-store` and
+ *    `Vary: X-Share-Password` on every outcome, and the authenticated routes
+ *    do not;
+ *  - the pure-JS scrypt the WebContainer path uses and `node:crypto`'s produce
+ *    interchangeable hashes.
  */
 
 import { describe, it, expect, afterEach, vi } from 'vitest';
@@ -98,15 +103,15 @@ async function drive(
     headers?: Record<string, string>;
     body?: unknown;
   } = {},
-): Promise<{ status: number; body: any }> {
+): Promise<{ status: number; body: any; headers: Record<string, string | string[]> }> {
   const handler = http.routes.get(key);
   if (!handler) throw new Error(`no handler for ${key}`);
-  const captured = { status: 200, body: undefined as any };
+  const captured = { status: 200, body: undefined as any, headers: {} as Record<string, string | string[]> };
   const res: IHttpResponse = {
     json: vi.fn((data: any) => { captured.body = data; }) as any,
     send: vi.fn() as any,
     status: vi.fn((code: number) => { captured.status = code; return res; }) as any,
-    header: vi.fn(() => res) as any,
+    header: vi.fn((name: string, value: string | string[]) => { captured.headers[name] = value; return res; }) as any,
   };
   const req: IHttpRequest = {
     params: opts.params ?? {},
@@ -472,3 +477,41 @@ describe('[#21839] how the password travels in', () => {
     expect(loggedText(logger)).not.toContain('wrong one 21839');
   });
 });
+
+describe('[#21839] the public routes are never cached', () => {
+  function expectNoStore(res: { headers: Record<string, string | string[]> }, label: string) {
+    expect(res.headers['Cache-Control'], label).toBe('no-store');
+    expect(res.headers.Vary, label).toBe('X-Share-Password');
+  }
+
+  it.each(['resolve', 'messages'] as const)('/%s sends no-store + Vary on success and on every refusal', async (route) => {
+    const booted = await boot();
+    const link = await booted.service.createLink(
+      { object: 'ai_conversations', recordId: 'conv_1', password: PASSWORD },
+      CREATOR,
+    );
+    const key = `GET ${B}/:token/${route}`;
+    const ok = await drive(booted.http, key, { params: { token: link.token }, headers: { 'x-share-password': PASSWORD } });
+    expect(ok.status).toBe(200);
+    expectNoStore(ok, 'success');
+
+    const bare = await drive(booted.http, key, { params: { token: link.token } });
+    expect(bare.status).not.toBe(200);
+    expectNoStore(bare, 'no password');
+
+    const wrong = await drive(booted.http, key, { params: { token: link.token }, query: { password: 'nope 21839' } });
+    expect(wrong.status).not.toBe(200);
+    expectNoStore(wrong, 'wrong password');
+
+    const unknown = await drive(booted.http, key, { params: { token: 'no-such-token-21839' } });
+    expect(unknown.status).toBe(404);
+    expectNoStore(unknown, 'unknown token');
+  });
+
+  it('the authenticated list route is not given the public headers', async () => {
+    const { http } = await boot();
+    const res = await drive(http, `GET ${B}`);
+    expect(res.headers['Cache-Control']).toBeUndefined();
+    expect(res.headers.Vary).toBeUndefined();
+  });
+});

packages/plugins/plugin-sharing/src/share-link-password.ts

@@ -11,8 +11,19 @@
  * carries for WebContainer): N=16384, r=16, p=1, a 64-byte key, a 16-byte
  * random salt passed as its hex string, and the password NFKC-normalised.
  * Same algorithm and parameters, so a share-link password is exactly as
- * expensive to brute-force from a database dump as a sign-in password. The
- * implementation is `node:crypto`'s scrypt — no new dependency.
+ * expensive to brute-force from a database dump as a sign-in password.
+ *
+ * ## Two implementations, one hash
+ *
+ * On Node the key is derived by `node:crypto`'s scrypt. WebContainer
+ * (StackBlitz) reports itself as Node but polyfills `node:crypto.scrypt`
+ * incompletely, so there — detected exactly as `plugin-auth`'s
+ * `isWebContainerRuntime()` detects it — the key is derived by
+ * `@noble/hashes/scrypt` instead, the same pure-JS scrypt `plugin-auth` swaps
+ * in for account passwords on that host. Same parameters, same salt input,
+ * same output bytes: a hash minted by either verifies under the other, so a
+ * link created in a WebContainer keeps working when the app is deployed. The
+ * pure-JS module is loaded only on that host; elsewhere it is never imported.
  *
  * ## The legacy forms, and why they are upgraded on read rather than migrated
  *
@@ -47,7 +58,38 @@ const CURRENT_PREFIX = 'scrypt$';
 const LEGACY_SHA256_PREFIX = 'sha256$';
 const LEGACY_PLAINTEXT_PREFIX = 'weak$';
 
+/**
+ * WebContainer (StackBlitz) detection — the same three signals `plugin-auth`'s
+ * `isWebContainerRuntime()` and `service-settings`' local crypto provider read.
+ */
+function isWebContainerRuntime(): boolean {
+  const proc = (globalThis as { process?: { versions?: Record<string, unknown>; env?: Record<string, unknown> } })
+    .process;
+  return (
+    Boolean(proc?.versions?.webcontainer) ||
+    (typeof proc?.env?.SHELL === 'string' && proc.env.SHELL.includes('jsh')) ||
+    Boolean(proc?.env?.STACKBLITZ)
+  );
+}
+
+/** The pure-JS scrypt, with exactly the parameters {@link deriveKeyNode} passes. */
+async function deriveKeyPureJs(password: string, saltHex: string): Promise<Buffer> {
+  const { scryptAsync } = await import('@noble/hashes/scrypt.js');
+  const key = await scryptAsync(password.normalize('NFKC'), saltHex, {
+    N: SCRYPT_N,
+    r: SCRYPT_R,
+    p: SCRYPT_P,
+    dkLen: SCRYPT_KEY_BYTES,
+    maxmem: SCRYPT_MAXMEM,
+  });
+  return Buffer.from(key);
+}
+
 function deriveKey(password: string, saltHex: string): Promise<Buffer> {
+  return isWebContainerRuntime() ? deriveKeyPureJs(password, saltHex) : deriveKeyNode(password, saltHex);
+}
+
+function deriveKeyNode(password: string, saltHex: string): Promise<Buffer> {
   return new Promise((resolve, reject) => {
     scrypt(
       password.normalize('NFKC'),

packages/plugins/plugin-sharing/src/share-link-routes.ts

@@ -30,7 +30,7 @@
  * and renders the response read-only.
  */
 
-import type { IHttpServer, IHttpRequest, RouteHandler } from '@objectstack/spec/contracts';
+import type { IHttpServer, IHttpRequest, IHttpResponse, RouteHandler } from '@objectstack/spec/contracts';
 // The declared envelope is written in ONE place for the whole platform (#3973).
 import { sendOk, sendError } from '@objectstack/types';
 import type { ShareLinkExecutionContext } from '@objectstack/spec/contracts';
@@ -149,6 +149,27 @@ function presentedPassword(req: IHttpRequest): string | undefined {
   return typeof header === 'string' ? header : undefined;
 }
 
+/**
+ * [#21839] Response headers both public routes (`/resolve` and `/messages`)
+ * answer with, on every outcome.
+ *
+ * `Cache-Control: no-store` — the body is a record released by a capability
+ * token (and, for a protected link, by a password); no browser or shared cache
+ * may keep a copy of it, nor of a refusal that would be replayed after the
+ * link changes. `Vary: X-Share-Password` — the answer depends on that request
+ * header, so any cache that does not honour `no-store` must at least never
+ * serve one presenter's answer to another. The dispatcher twin
+ * (`runtime/src/domains/share-links.ts`) sends the same pair.
+ */
+const SHARE_LINK_PUBLIC_RESPONSE_HEADERS: Readonly<Record<string, string>> = Object.freeze({
+  'Cache-Control': 'no-store',
+  Vary: 'X-Share-Password',
+});
+
+function setPublicResponseHeaders(res: IHttpResponse): void {
+  for (const [name, value] of Object.entries(SHARE_LINK_PUBLIC_RESPONSE_HEADERS)) res.header(name, value);
+}
+
 /** Strip `redactFields` from a record (also removes from nested arrays of objects). */
 function applyRedaction(record: any, redactFields: string[]): any {
   if (!record || typeof record !== 'object' || redactFields.length === 0) return record;
@@ -248,6 +269,7 @@ export function registerShareLinkRoutes(
   // No `ctxOf` here — the token IS the authorisation. We still allow
   // probes from a signed-in user so audience=signed_in is satisfiable.
   http.get(`${base}/:token/resolve`, (async (req, res) => {
+    setPublicResponseHeaders(res);
     try {
       const q = req.query ?? {};
       // [Finding-2] The `audience: 'signed_in'` gate must key off the VERIFIED
@@ -381,6 +403,7 @@ export function registerShareLinkRoutes(
   // following the same pattern.
   // ──────────────────────────────────────────────────────────────
   http.get(`${base}/:token/messages`, (async (req, res) => {
+    setPublicResponseHeaders(res);
     try {
       const resolved = await service.resolveToken(req.params.token, {
         providedPassword: presentedPassword(req),