fix(plugin-sharing): share-link password never leaves the server, is stored with the platform slow hash, and is accepted in a header

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

@@ -0,0 +1,15 @@
+---
+'@objectstack/plugin-sharing': patch
+'@objectstack/plugin-hono-server': patch
+'@objectstack/hono': 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/permissions/tenant-audit-census.mdx

@@ -122,7 +122,7 @@ are reported as `undecidable` rather than assumed either way.
 
 The same holds twice over for the context. An options argument spelled as a
 literal can be read; one spelled `options`, `{ ...opts }`, or handed through a
-forwarding shim cannot, and **67 of the 232 sites are spelled that way**. A
+forwarding shim cannot, and **67 of the 233 sites are spelled that way**. A
 context resolved from an inline literal or a local `const` can be tested for
 `isSystem`; one arriving from a helper call cannot.
 
@@ -187,10 +187,10 @@ reproduce them. Where it disagrees, it disagrees on the page:
 
 | carried figure | where it survives | this census |
 | :--- | :--- | ---: |
-| 175 write call sites | quoted in the merged changeset | **232** |
+| 175 write call sites | quoted in the merged changeset | **233** |
 | 24 carrying no tenant context | quoted in the merged changeset | **9** provable and tenancy-enabled; **34** more whose options argument is unreadable |
-| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **154 of 232** decidable, **78** undecidable |
-| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 113 decidably elevated, 0 decidably not, 102 undecidable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **155 of 233** decidable, **78** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 114 decidably elevated, 0 decidably not, 102 undecidable |
 | 141 and 132, two independent re-derivations | the card that filed this work | — |
 
 **The differences are not reconciled, and deliberately so.** The old census's
@@ -207,11 +207,11 @@ would report a smaller number and would not say so.
 
 The fourth row is the one worth flagging to anyone citing it. **The 135 / 77%
 figure has no surviving corroboration anywhere in the tree.** This census reads
-113 of 232 (49%) as decidably elevated, with 102 more whose elevation is a
+114 of 233 (49%) as decidably elevated, with 102 more whose elevation is a
 run-time fact — so the claim is neither confirmed nor refuted, and the honest
 answer is that a static reading cannot settle it.
 
-⇒ **Cite `9 / 232`, and say what it is**: the sites whose options argument was
+⇒ **Cite `9 / 233`, and say what it is**: the sites whose options argument was
 READ and holds no tenant context, against a decidably tenancy-enabled object.
 That is the control's provable yield surface. ⛔ Do not cite it as "the sites
 without tenant context" — **34 further sites** have an options argument this
@@ -223,28 +223,28 @@ cannot read, and they are neither in nor out.
 
 | what | count |
 | :--- | ---: |
-| write call sites on the application surface | **232** |
-| …whose object name is statically decidable | 154 |
+| write call sites on the application surface | **233** |
+| …whose object name is statically decidable | 155 |
 | …whose object name is chosen at run time | 78 |
-| …against an object with tenancy ENABLED | 153 |
+| …against an object with tenancy ENABLED | 154 |
 | …against an object that declares tenancy off | 1 |
-| threading a tenant context | 148 |
+| threading a tenant context | 149 |
 | PROVABLY carrying none (options read, no context key) | **17** |
 | …of those, against a decidably tenancy-enabled object | **9** |
 | options argument UNREADABLE — may or may not carry one | 67 |
 | …of those, against a decidably tenancy-enabled object | 34 |
-| threading a decidably ELEVATED (`isSystem`) context | 113 |
+| threading a decidably ELEVATED (`isSystem`) context | 114 |
 | threading a context that is decidably NOT elevated | 0 |
 | threading a context whose elevation is a run-time fact | 102 |
 
 | how the instrument reached the site | count |
 | :--- | ---: |
-| receiver carried a readable engine type | 184 |
+| receiver carried a readable engine type | 185 |
 | receiver erased, placed by the object NAME | 28 |
 | receiver erased, placed by an `object: string` PARAMETER | 15 |
 | receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
 
-| object name spelled inline | 103 |
+| object name spelled inline | 104 |
 | object name spelled through a `const` | 51 |
 | object name is an `object: string` parameter | 17 |
 | object name is some other run-time expression | 61 |
@@ -297,13 +297,13 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-05 at `34782539c`.
+Measured on 2026-10-05 at `3d34c6efd`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 605 |
-| engine-shaped types recognised | 68 |
+| tracked non-test sources scanned | 607 |
+| engine-shaped types recognised | 69 |
 | declared objects in the registry | 116 |
-| same-named calls subtracted as non-engine | 155 |
+| same-named calls subtracted as non-engine | 158 |
 
 {/* END GENERATED: tenant-audit-census */}

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

docs/audits/2026-08-tenant-audit-write-call-sites.counts.md

@@ -33,17 +33,17 @@ silent, and `node scripts/tenant-audit-census.mjs --write` is the resolution.
 
 | Measure | Value |
 |---|---:|
-| Write call sites | 232 |
-| Object name statically decidable | 154 |
+| Write call sites | 233 |
+| Object name statically decidable | 155 |
 | Object name chosen at run time | 78 |
-| Against a tenancy-enabled object | 153 |
+| Against a tenancy-enabled object | 154 |
 | Against an object declaring tenancy off | 1 |
-| Threading a tenant context | 148 |
+| Threading a tenant context | 149 |
 | Provably carrying none | 17 |
 | …and decidably tenancy-enabled | 9 |
 | Options argument unreadable | 67 |
 | …and decidably tenancy-enabled | 34 |
-| Threading a decidably elevated context | 113 |
+| Threading a decidably elevated context | 114 |
 | Threading a decidably non-elevated context | 0 |
 | Threading a context of undecidable elevation | 102 |
 
@@ -90,14 +90,14 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-05 at `34782539c`.
+Measured on 2026-10-05 at `3d34c6efd`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 605 |
-| engine-shaped types recognised | 68 |
+| tracked non-test sources scanned | 607 |
+| engine-shaped types recognised | 69 |
 | declared objects in the registry | 116 |
-| same-named calls subtracted as non-engine | 155 |
+| same-named calls subtracted as non-engine | 158 |
 
 ## Every site
 
@@ -183,7 +183,7 @@ Measured on 2026-10-05 at `34782539c`.
 | `packages/plugins/plugin-sharing/src/primary-bu-projection.ts` | `update` | `sys_user` | enabled | elevated | 2 |
 | `packages/plugins/plugin-sharing/src/record-orphan-cleanup.ts` | `delete` | `table` | undecidable | options unreadable | 2 |
 | `packages/plugins/plugin-sharing/src/share-link-service.ts` | `insert` | `sys_share_link` | enabled | elevated | 1 |
-| `packages/plugins/plugin-sharing/src/share-link-service.ts` | `update` | `sys_share_link` | enabled | elevated | 2 |
+| `packages/plugins/plugin-sharing/src/share-link-service.ts` | `update` | `sys_share_link` | enabled | elevated | 3 |
 | `packages/plugins/plugin-sharing/src/sharing-plugin.ts` | `update` | `object` | undecidable | elevated | 1 |
 | `packages/plugins/plugin-sharing/src/sharing-rule-service.ts` | `delete` | `sys_record_share` | enabled | options unreadable | 3 |
 | `packages/plugins/plugin-sharing/src/sharing-rule-service.ts` | `delete` | `sys_sharing_rule` | enabled | options unreadable | 1 |

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,107 @@
+// 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('a password whose NFKC form differs from its input is one password on both paths', async () => {
+    // A decomposed e + combining acute, and a fullwidth A: NFKC rewrites both.
+    const raw = 'cafe\u0301 \uFF21 21839';
+    const normalised = 'caf\u00e9 A 21839';
+    expect(raw).not.toBe(normalised);
+    expect(raw.normalize('NFKC')).toBe(normalised);
+
+    // pure-JS mints, native verifies — either spelling of the same password.
+    onWebContainer(true);
+    const pureJsHash = await hashShareLinkPassword(raw);
+    onWebContainer(false);
+    expect(await verifyShareLinkPassword(raw, pureJsHash)).toBe(true);
+    expect(await verifyShareLinkPassword(normalised, pureJsHash)).toBe(true);
+    expect(await verifyShareLinkPassword('cafe A 21839', pureJsHash)).toBe(false);
+
+    // native mints, pure-JS verifies — either spelling of the same password.
+    onWebContainer(false);
+    const nativeHash = await hashShareLinkPassword(raw);
+    onWebContainer(true);
+    nodeScrypt.mockClear();
+    expect(await verifyShareLinkPassword(raw, nativeHash)).toBe(true);
+    expect(await verifyShareLinkPassword(normalised, nativeHash)).toBe(true);
+    expect(await verifyShareLinkPassword('cafe A 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);
+  });
+});